Mayor: Add gt_rig_browse tool for on-demand rig code inspection

[jrf0110]

Parent

Part of #204 (Phase 3: Multi-Rig + Scaling)

Problem

After a container restart (sleep/wake, deploy, OOM), the rig workspace is empty — /workspace/rigs/{rigId}/ has no cloned repos. Git clones only happen when a polecat or refinery agent is dispatched (cloneRepo() in agent-runner.ts:383). The Mayor is never cloned into a real repo — it gets a fake git init + empty commit workspace (createMayorWorkspace() in agent-runner.ts:335-361).

When a user asks the Mayor to look at a rig's code — understand the codebase structure, check what files exist, review a specific file — the Mayor has no way to do this. It has no git tools, no file browsing tools, and no awareness in its system prompt that rig repos may not be available. The Mayor either hallucinates an answer or fails silently.

The right intermediate solution is a gt_rig_browse tool that lets the Mayor inspect rig contents on demand, with the git plumbing handled transparently by the container. If the repo isn't cloned yet, clone it. If it's stale, fetch. Then return the requested information.

This is deliberately scoped as an intermediate solution. Full container state recovery (checkpoint/restore, persistent volumes) is tracked in #269.

Current Architecture

• Mayor workspace: git init + empty commit at /workspace/rigs/mayor-{townId}/mayor-workspace — no real repo (agent-runner.ts:335-361)
• Mayor tools: gt_sling, gt_sling_batch, gt_list_rigs, gt_list_beads, gt_list_agents, gt_list_convoys, gt_convoy_status, gt_mail_send — no git or file operations (container/plugin/mayor-tools.ts)
• Mayor prompt: Says "You are NOT a worker. You do not write code, run tests, or make commits." Says nothing about rig state, git repos, or how to inspect code (src/prompts/mayor-system.prompt.ts)
• Git clone trigger: Only runAgent() for non-mayor roles and mergeBranch() call cloneRepo() — the Mayor path skips it entirely (agent-runner.ts:374)

Solution

1. gt_rig_browse Mayor tool

A new tool that lets the Mayor inspect a rig's codebase. The tool sends a request to the container, which handles git plumbing transparently:

gt_rig_browse:
  rig_id: string (required)
  path: string (optional, default "/")
  action: "tree" | "read" (default "tree")

• tree: Returns a directory listing (file names, types, sizes) for the given path. Recursive to a configurable depth.
• read: Returns the contents of a specific file (with size limits to avoid blowing up context).

2. Container endpoint: GET /rigs/:rigId/browse

New container endpoint that:

1. Checks if /workspace/rigs/{rigId}/repo exists
2. If not → calls cloneRepo() to clone the rig's repo (using credentials from the request or resolved dynamically)
3. If yes → optionally runs git fetch if the repo is stale (last fetch > N minutes ago)
4. Checks out the default branch in a temporary read-only worktree (or reads from the bare repo directly)
5. Returns the requested file tree or file contents

This endpoint needs git credentials. Options:

• Pass credentials in the request (from TownDO's rig config)
• Use the existing resolveGitCredentialsIfMissing() flow

3. Mayor prompt update

Add a section to src/prompts/mayor-system.prompt.ts:

## Inspecting Rig Code

You can browse a rig's codebase using gt_rig_browse. Use this when you need to 
understand a repo's structure before delegating work, or when answering questions 
about the codebase.

- gt_rig_browse with action "tree" to see the directory structure
- gt_rig_browse with action "read" to read a specific file

The rig's repo is fetched automatically if needed. You don't need to worry about 
whether the container has the code — the tool handles it.

Acceptance Criteria

• gt_rig_browse tool added to mayor tools (container/plugin/mayor-tools.ts)
• Container endpoint GET /rigs/:rigId/browse handles clone-on-demand, fetch-if-stale, and returns file tree or file contents
• Mayor system prompt updated with rig inspection guidance
• Tool works correctly on a fresh container (triggers clone)
• Tool works correctly on a warm container (uses existing clone, optionally fetches)
• File reads are size-limited to prevent context blowout
• Git credentials are resolved correctly for the rig's integration

Notes

• No data migration needed — cloud Gastown hasn't deployed to production
• This does NOT give the Mayor write access to the repo — it's read-only inspection
• Full container state recovery (persistent workspaces across restarts) is tracked in [Gastown] PR 18: Container Resilience — Checkpoint/Restore #269 — this issue is specifically about giving the Mayor a tool to browse rig code on demand
• The cloneRepo() function in container/src/git-manager.ts already handles the clone-or-fetch logic — the new endpoint can reuse it directly
• Consider whether gt_rig_browse should also support browsing a specific branch/ref (useful for inspecting a polecat's work branch)

[jrf0110]

We opted for adding rigs into the mayor's workspace and telling them about where to find those rigs and encourage him to treat them as readonly