Workspace Supervisor

The Workspace Supervisor organizes long-running, multi-panel work: charters, intake, run history, loops, readiness, and optional LLM review. It is an execution layer after you know the goal — not the first place to invent a vague chat.

One job

Emit a card. Show the queue. Stop until a human decides.

1. 01
   CI / PR wake

   Supervisor reads already-fetched sidebar checks, emits an approvable card, and stops. It is not a GitHub webhook.

2. 02
   Queue is visible

   Task phase is queued / claimed / running. Humans can see the queue. It does not replace waiting-approval on the phone.

3. 03
   One card schema

   IDE inbox and imux Mobile share imux.proposed-action.v1. Decide on the Mac. The phone is read-only this slice.

When to use Supervisor (and when not to)

Use it at transitions: starting a multi-step job, after a failure, or before handoff. Prefer a terminal agent CLI or Agent Chat for single-threaded coding tasks. Do not run Supervisor loops on every keystroke.

Task Charters

Define what a workspace should do with a task charter:

• A charter is a concise statement of the workspace objective: what to accomplish, relevant files, and success criteria.
• The charter stays attached to the workspace, providing persistent context even when you switch tasks or return after a break.
• Update the charter as the objective evolves, keeping the workspace aligned with the current goal.

Startup and Session Intake

When a workspace session begins, the supervisor captures the starting state:

• Records the initial working directory, Git branch, open files, and any explicit task charter.
• Produces a startup brief that summarizes what the workspace should accomplish in this session.
• The intake snapshot is stored with the session so you can review what was planned versus what was done.

Run History

Track task execution over time with structured run history:

• Each supervised run records start time, end time, outcome, and any artifacts produced.
• Run history is stored per-workspace, so you can trace the full lifecycle of a task across multiple sessions.
• Use run history to review what was tried, what succeeded, and what still needs attention.

CI / PR proposed actions

When sidebar checks go red, or a current-branch PR is green, Supervisor emits an approvable card and stops. It does not start another silent loop round.

• Same schema on the IDE inbox and imux Mobile. Decide on the Mac; the phone is read-only this slice.
• v1 reads already-fetched sidebar pull-request checks. It is not a GitHub webhook.
• Approve records the decision. Start the loop yourself for the next round. Dismiss and defer never auto-loop.

Task queue

A task has a run phase beside its status so the queue is visible while work is claimed.

• runPhase is queued, claimed, or running. New tasks start queued.
• status stays active / completed / failed / cancelled. Phone waiting-approval is a different field.
• Legacy conversations without runPhase decode as running so old sessions keep their meaning.

What we don’t add

• A CI webhook or a silent extra loop after the card.
• A meeting bot or a second ticket tracker.
• A phone decide API this slice — approve on the Mac.
• A Bot decide surface in this repository.

Loop Settings

Configure retry and restart behavior for supervised tasks:

• Set the maximum number of retry attempts before the supervisor marks a task as failed.
• Define a delay between retries to allow external conditions (builds, deploys, tests) to settle.
• Customize restart behavior: always restart on failure, prompt before retrying, or stop after the first failure.

Readiness Probes

Define health checks for workspace tasks:

• A readiness probe is a command or script that the supervisor runs to check whether a task is healthy and making progress.
• Probes can check file existence, process state, network connectivity, or any custom condition relevant to the task.
• If a probe fails repeatedly, the supervisor can trigger a restart, notification, or escalation based on loop settings.

LLM-Backed Review State

Optionally enable AI review of task output:

• After each run, the supervisor can send the output and workspace context to an LLM for automated review.
• The LLM review flags issues, suggests improvements, and provides a structured assessment of the task outcome.
• Review state is attached to the run history entry, giving you both human and AI perspectives on task progress.

Session Persistence

Supervisor state is per-workspace and persists across app restarts:

• Charters, run history, loop settings, and review state are all encoded in session snapshots.
• When you quit and relaunch imux, each workspace restores its supervisor state alongside its layout.
• Session snapshots respect autosave limits for windows, workspaces, layout depth, and scrollback, so supervisor data does not cause unbounded growth.