indusagi-coding-agent 0.2.2 → 0.2.3

package/dist/types/boot/runners/delegate-runner.d.ts

@@ -43,6 +43,12 @@ export interface DelegateSubAgent {
         messages: readonly AgentMessage[];
         error?: string;
     };
+    /**
+     * Optional event subscription (the real framework `Agent` provides it). The
+     * runner uses it to recompute live token spend as the sub-agent works; a test
+     * fake may omit it, in which case no progress is reported.
+     */
+    subscribe?(listener: () => void): () => void;
 }
 /** Configuration for {@link createDelegateRunner}. */
 export interface DelegateRunnerOptions {

package/dist/types/boot/runners/session.d.ts

@@ -11,6 +11,7 @@
 import { type AgentTool, type SessionConductor } from "../../conductor";
 import { type MemoryStore } from "../../capability-deck";
 import { type DelegateRunner } from "../../capability-deck/cards/task-card";
+import type { WorkflowAgentRunner } from "../../workflow-engine";
 import { type CheckpointStore } from "./checkpoint";
 import { type ContextDoc, type SkillCard } from "../../briefing";
 import type { BootContext, Invocation } from "../contract";
@@ -33,23 +34,7 @@ export declare function resolveModelId(ctx: BootContext): string;
  * bad/unreadable skills dir never sinks the session.
  */
 export declare function gatherModelSkills(cwd: string): SkillCard[];
-/**
- * Select the tool deck for the run, honouring `--no-tools` (empty) and `--tools`
- * (allow-list). Tool ids are matched case-insensitively with `_`/`-` stripped, so
- * a `--tools web_fetch,todo_read` request lines up with the deck's `webfetch` /
- * `todoread` ids.
- */
-/**
- * @param runner an optional live sub-agent {@link DelegateRunner}; when present it
- *   is injected under {@link DELEGATE_HANDLE_KEY} so the `task` card delegates for
- *   real instead of returning its `STUB_NOTE`. Omitted by callers that only need
- *   a deck (the card then degrades gracefully).
- * @param checkpoint an optional per-session {@link CheckpointStore}; when present
- *   it is injected under {@link CHECKPOINT_HANDLE_KEY} so the framework's
- *   write/edit tools snapshot a file's pre-mutation content (rewind, #24). Omitted
- *   callers get no checkpointing (the tools no-op the snapshot).
- */
-export declare function selectTools(cwd: string, inv: Invocation, runner?: DelegateRunner, memoryStore?: MemoryStore, checkpoint?: CheckpointStore): AgentTool[];
+export declare function selectTools(cwd: string, inv: Invocation, runner?: DelegateRunner, memoryStore?: MemoryStore, checkpoint?: CheckpointStore, workflowRunner?: WorkflowAgentRunner): AgentTool[];
 /**
  * Compose the run's system prompt: `--system` replaces the built-in briefing,
  * `--append-system` adds a trailing block, and both compose (override then

package/dist/types/capability-deck/cards/index.d.ts

@@ -21,6 +21,7 @@ import type { CapabilityCard } from "../contract";
 export { todoCard, buildTodoCapability, TodoLedger, type TodoItem, type TodoState, type TodoWeight, type TodoParamsType, type TodoDetails, } from "./todo-card";
 export { daemonCard, buildDaemonCapability, DaemonTable, type DaemonState, type DaemonParamsType, type DaemonDetails, } from "./bg-process-card";
 export { taskCard, buildTaskCapability, DELEGATE_HANDLE_KEY, type DelegateRunner, type DelegateRequest, type DelegateResult, type TaskParamsType, type TaskDetails, } from "./task-card";
+export { workflowCard, buildWorkflowCapability, WORKFLOW_HANDLE_KEY, type WorkflowParamsType, type WorkflowDetails, } from "./workflow-card";
 export { saasCard, buildSaasCapability, SAAS_GATEWAY_KEY, type SaasGatewayPort, type RemoteToolSummary, type RemoteExecution, type SaasParamsType, type SaasDetails, } from "./saas-card";
 export { memoryCard, buildMemoryCapability, InMemoryStore, MEMORY_HANDLE_KEY, type MemoryStore, type MemoryParamsType, type MemoryDetails, } from "./memory-card";
 export { enterPlanModeCard, exitPlanModeCard, buildEnterPlanModeCapability, buildExitPlanModeCapability, PLAN_HANDLE_KEY, type PlanController, type EnterPlanParamsType, type EnterPlanDetails, type ExitPlanParamsType, type ExitPlanDetails, } from "./plan-tools";

package/dist/types/capability-deck/cards/task-card.d.ts

@@ -37,6 +37,20 @@ export interface DelegateResult {
     /** The sub-agent's final report, surfaced to the parent agent verbatim. */
     readonly report: string;
 }
+/** One line of a sub-agent's live activity stream (for the drill-in view). */
+export interface ActivityLine {
+    /** What kind of step this is, used to colour it. */
+    readonly tone: "reason" | "tool" | "result";
+    /** The display text (already shortened to a single line). */
+    readonly text: string;
+}
+/** Live progress a running sub-agent streams back while it works. */
+export interface DelegateProgress {
+    /** Cumulative tokens the sub-agent has spent so far (input + output). */
+    readonly tokens: number;
+    /** The sub-agent's recent activity (reasoning + tool steps), newest last. */
+    readonly activity: readonly ActivityLine[];
+}
 /**
  * The contract a host's sub-agent runner must satisfy to be wired in.
  *
@@ -47,8 +61,14 @@ export interface DelegateResult {
 export interface DelegateRunner {
     /** Optional roster of named agent profiles, surfaced in the tool description. */
     listAgents?(): readonly string[];
-    /** Run one delegated objective and resolve with the sub-agent's report. */
-    run(request: DelegateRequest, signal?: AbortSignal): Promise<DelegateResult>;
+    /**
+     * Run one delegated objective and resolve with the sub-agent's report.
+     *
+     * When an `onProgress` callback is supplied the runner streams live metrics
+     * (token spend) as the sub-agent works, so the host can surface them (the
+     * background-agents panel). Optional — a runner may ignore it.
+     */
+    run(request: DelegateRequest, signal?: AbortSignal, onProgress?: (progress: DelegateProgress) => void): Promise<DelegateResult>;
 }
 declare const TaskParams: import("@sinclair/typebox").TObject<{
     objective: import("@sinclair/typebox").TString;
@@ -65,6 +85,10 @@ export interface TaskDetails {
     readonly ok: boolean;
     /** The agent profile that ran, if one was named. */
     readonly agent?: string;
+    /** Cumulative tokens the sub-agent spent — streamed live on progress updates. */
+    readonly tokens?: number;
+    /** The sub-agent's recent activity — streamed live for the drill-in view. */
+    readonly activity?: readonly ActivityLine[];
 }
 /**
  * Build the task/delegate capability.

package/dist/types/capability-deck/cards/workflow-card.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Workflow capability — orchestrate a deterministic fan-out of subagents.
+ *
+ * App-novel wiring, sibling to (and UNRELATED to) the {@link "./task-card"}
+ * delegate card. The `workflow` tool runs a deterministic JavaScript workflow
+ * script that calls `agent()`, `parallel()`, and `pipeline()` to fan work out
+ * across many fresh subagents and fan their results back in, all under a live
+ * `◆ Workflow:` progress tree streamed into the tool result.
+ *
+ * The actual subagent runner is NOT owned by this card — it is a framework /
+ * boot concern injected through {@link DeckContext.framework} under the
+ * {@link WORKFLOW_HANDLE_KEY} key. When that handle is present the capability
+ * really runs the workflow (via the pure {@link runWorkflow} engine); when it is
+ * absent (tests, headless tooling, a host that has not wired the runner) the
+ * capability degrades gracefully to a clearly-typed {@link STUB_NOTE} result
+ * rather than throwing, exactly like the task card's `readDelegateRunner` path.
+ *
+ * Recursion guard: this card is registered all-profile-only in
+ * {@link "../cards/index"} (`APP_NOVEL_CARDS`), so the `'authoring'` deck a
+ * workflow subagent runs against EXCLUDES it — a subagent cannot call `workflow`.
+ *
+ * Live UI: each engine lifecycle callback mutates a {@link WorkflowSnapshot} and
+ * calls the framework `onUpdate` with the snapshot rendered through
+ * {@link renderWorkflowText} (the v1 string renderer). Updates are coalesced to
+ * status transitions (phase / agent start / agent end), not every log line, to
+ * avoid render thrash. The conductor re-projects the framework
+ * `tool_execution_update` event to a `tool_update` product signal (stage 3).
+ */
+import { type Static } from "@sinclair/typebox";
+import type { Capability, CapabilityCard, DeckContext } from "../contract";
+import { type WorkflowSnapshot } from "../../workflow-engine";
+/** Key under which a host wires a live workflow agent runner into the context. */
+export declare const WORKFLOW_HANDLE_KEY: "workflow";
+declare const WorkflowParams: import("@sinclair/typebox").TObject<{
+    script: import("@sinclair/typebox").TString;
+    args: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TAny>;
+}>;
+/** Statically-inferred parameter type the capability's `execute` receives. */
+export type WorkflowParamsType = Static<typeof WorkflowParams>;
+/** Structured detail returned alongside the model-facing content (the snapshot). */
+export type WorkflowDetails = WorkflowSnapshot;
+/**
+ * Build the workflow capability.
+ *
+ * If a {@link WorkflowAgentRunner} is present on the context it is bound and the
+ * tool truly orchestrates; otherwise the tool builds anyway and returns a typed,
+ * non-throwing stub so the deck stays assemblable in every environment.
+ *
+ * @param ctx the deck context; an optional runner is read from
+ *            `ctx.framework[WORKFLOW_HANDLE_KEY]`.
+ */
+export declare function buildWorkflowCapability(ctx: DeckContext): Capability<typeof WorkflowParams, WorkflowDetails>;
+/** Catalog row for the workflow capability. */
+export declare const workflowCard: CapabilityCard;
+export {};

package/dist/types/capability-deck/cards/workflow-card.test.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Workflow card — focused unit tests.
+ *
+ * The card is a pure capability builder over the pure {@link runWorkflow} engine
+ * (an injected {@link WorkflowAgentRunner} does the spawning). These tests cover:
+ *   - the STUB_NOTE degrade when no runner handle is wired (no throw),
+ *   - a real run with an in-memory fake runner: lifecycle → snapshot,
+ *   - abort flips running agents to skipped,
+ *   - and the deck-assembly guarantee: workflow appears in the `all` profile but
+ *     NOT in the `authoring` subagent profile (the recursion guard).
+ */
+export {};

package/dist/types/capability-deck/index.d.ts

@@ -31,7 +31,7 @@ export { CAPABILITY_CARDS, CAPABILITY_INDEX, CARD_PROFILES, capabilityIds, hasCa
  * (checklist, background-process proxy, delegate/sub-agent, SaaS connector,
  * working memory) plus their builders, stores, and injection-handle types.
  */
-export { APP_NOVEL_CARDS, todoCard, buildTodoCapability, TodoLedger, type TodoItem, type TodoState, type TodoWeight, type TodoParamsType, type TodoDetails, daemonCard, buildDaemonCapability, DaemonTable, type DaemonState, type DaemonParamsType, type DaemonDetails, taskCard, buildTaskCapability, DELEGATE_HANDLE_KEY, type DelegateRunner, type DelegateRequest, type DelegateResult, type TaskParamsType, type TaskDetails, saasCard, buildSaasCapability, SAAS_GATEWAY_KEY, type SaasGatewayPort, type RemoteToolSummary, type RemoteExecution, type SaasParamsType, type SaasDetails, memoryCard, buildMemoryCapability, InMemoryStore, MEMORY_HANDLE_KEY, type MemoryStore, type MemoryParamsType, type MemoryDetails, enterPlanModeCard, exitPlanModeCard, buildEnterPlanModeCapability, buildExitPlanModeCapability, PLAN_HANDLE_KEY, planSlug, planFilePath, writePlan, readPlan, PLANS_DIRNAME, type PlanController, type EnterPlanParamsType, type EnterPlanDetails, type ExitPlanParamsType, type ExitPlanDetails, } from "./cards/index";
+export { APP_NOVEL_CARDS, todoCard, buildTodoCapability, TodoLedger, type TodoItem, type TodoState, type TodoWeight, type TodoParamsType, type TodoDetails, daemonCard, buildDaemonCapability, DaemonTable, type DaemonState, type DaemonParamsType, type DaemonDetails, taskCard, buildTaskCapability, DELEGATE_HANDLE_KEY, type DelegateRunner, type DelegateRequest, type DelegateResult, type TaskParamsType, type TaskDetails, workflowCard, buildWorkflowCapability, WORKFLOW_HANDLE_KEY, type WorkflowParamsType, type WorkflowDetails, saasCard, buildSaasCapability, SAAS_GATEWAY_KEY, type SaasGatewayPort, type RemoteToolSummary, type RemoteExecution, type SaasParamsType, type SaasDetails, memoryCard, buildMemoryCapability, InMemoryStore, MEMORY_HANDLE_KEY, type MemoryStore, type MemoryParamsType, type MemoryDetails, enterPlanModeCard, exitPlanModeCard, buildEnterPlanModeCapability, buildExitPlanModeCapability, PLAN_HANDLE_KEY, planSlug, planFilePath, writePlan, readPlan, PLANS_DIRNAME, type PlanController, type EnterPlanParamsType, type EnterPlanDetails, type ExitPlanParamsType, type ExitPlanDetails, } from "./cards/index";
 /**
  * Bridge ledger — event-sourced enrollment of dynamically grafted MCP tools:
  * content-hash / ULID key minting, the immutable {@link BridgeLedger} value with

package/dist/types/conductor/contract.d.ts

@@ -97,6 +97,9 @@ export declare function conductorFault(kind: FaultKind, message: string, cause?:
  *   - `text`      — a chunk of assistant answer text streamed in.
  *   - `thinking`  — a chunk of reasoning/thinking text streamed in.
  *   - `tool_start`— a tool invocation began (correlate by `id`).
+ *   - `tool_update`— a running tool emitted partial progress (correlate by `id`);
+ *                   `name` is the tool name and `details` is the tool's own typed
+ *                   partial-result detail (e.g. the live `◆ Workflow` snapshot).
  *   - `tool_end`  — a tool invocation finished (`ok` = no error).
  *   - `turn_end`  — the assistant turn settled; `usage` reports token spend.
  *   - `persisted` — the latest node was committed to the transcript (`entryId`).
@@ -118,6 +121,11 @@ export type SessionSignal = {
     readonly kind: "tool_start";
     readonly id: string;
     readonly name: string;
+} | {
+    readonly kind: "tool_update";
+    readonly id: string;
+    readonly name: string;
+    readonly details: unknown;
 } | {
     readonly kind: "tool_end";
     readonly id: string;

package/dist/types/conductor/signal-hub/translate.d.ts

@@ -24,7 +24,10 @@
  *                                   (the turn is now committed), one `fault` for
  *                                   an errored *assistant* message, else `[]`
  *   - `tool_execution_start`     → one `tool_start`  { id, name }
- *   - `tool_execution_update`    → `[]`  (partial tool progress is not surfaced)
+ *   - `tool_execution_update`    → one `tool_update` { id, name, details } — the
+ *                                   running tool's partial-result detail (e.g. the
+ *                                   live `◆ Workflow` snapshot) re-projected so the
+ *                                   console can update the transcript in place
  *   - `tool_execution_end`       → one `tool_end`    { id, ok: !isError }
  *   - `turn_end`                 → one `turn_end`    { usage }
  *   - `message_update`           → delegated to the inner streaming dispatch on

package/dist/types/console/components/AgentsView.d.ts

@@ -0,0 +1,41 @@
+/**
+ * AgentsView — the drill-in sub-agent view, styled to the "IndusCode Saffron ·
+ * Subagent View" design.
+ *
+ * Opened from the main screen (← on an empty prompt while sub-agents are
+ * running), this replaces the transcript with a focused, navigable view of the
+ * delegated sub-agents: ↑/↓ moves the selection through `main` + each sub-agent,
+ * and the panel above the picker live-previews the selected sub-agent's activity
+ * stream — its reasoning and the tools it is using, just like the main screen —
+ * with a running clock and token count. Selecting `main` and pressing Enter (or
+ * Esc) returns to the main session.
+ *
+ * It is fed entirely by props the surface already holds: the derived
+ * {@link AgentRun}s plus the per-sub-agent live activity / token maps captured
+ * from the task tool's streamed progress. Its own {@link useInput} owns the
+ * keyboard while it is mounted (the surface gates its main handler off).
+ */
+import { type InkThemeAdapter } from "indusagi/react-ink";
+import type { AgentRun } from "./BackgroundAgents";
+import type { ActivityLine } from "../../capability-deck/cards/task-card";
+/** What the {@link AgentsView} renders. */
+export interface AgentsViewProps {
+    /** The framework adapter that turns token roles into terminal colours. */
+    readonly theme: InkThemeAdapter;
+    /** The delegated sub-agent runs (from `deriveAgentRuns`). */
+    readonly runs: readonly AgentRun[];
+    /** Live activity streams per run id (from the task tool's progress). */
+    readonly activity: Readonly<Record<string, readonly ActivityLine[]>>;
+    /** Live token spend per run id. */
+    readonly tokens: Readonly<Record<string, number>>;
+    /** Current epoch ms, for the run clock. Defaults to `Date.now()`. */
+    readonly now?: number;
+    /** Return to the main session. */
+    readonly onExit: () => void;
+}
+/**
+ * Render the drill-in agents view.
+ *
+ * @param props the theme, runs, live activity/token maps, and the exit callback
+ */
+export declare function AgentsView({ theme, runs, activity, tokens, now, onExit }: AgentsViewProps): JSX.Element;

package/dist/types/console/components/BackgroundAgents.d.ts

@@ -0,0 +1,63 @@
+/**
+ * BackgroundAgents — the live sub-agent panel pinned below the input, styled to
+ * the "IndusCode Saffron · Background Agents" design.
+ *
+ * When the primary agent delegates with the `task` tool, each sub-agent run is
+ * surfaced here as a compact status row (a spinner/● dot, the agent profile name
+ * in saffron, the objective in dim, and a running clock / done / failed status)
+ * under a `● main` header — so a user watching several agents work sees them all
+ * at a glance in the main screen instead of scrolling the transcript. The panel
+ * shows only while at least one run is in flight and hides once they all settle
+ * (their final reports remain inline in the transcript).
+ *
+ * The run list is derived purely from the conversation by {@link deriveAgentRuns}
+ * (the `task` tool calls in the assistant messages, matched against their
+ * `toolResult` messages for status), so the panel needs no extra session state —
+ * it is a projection of `conductor.messages()`.
+ */
+import { type InkThemeAdapter } from "indusagi/react-ink";
+import type { AgentMessage } from "indusagi/agent";
+/** The live status of one delegated sub-agent. */
+export type AgentRunStatus = "running" | "done" | "error";
+/** One delegated sub-agent run, projected from the conversation. */
+export interface AgentRun {
+    /** The `task` tool-call id correlating the call with its result. */
+    readonly id: string;
+    /** The agent profile name (the `agent` arg), or "subagent" when unnamed. */
+    readonly name: string;
+    /** The delegated objective (the `objective` arg), shown as the description. */
+    readonly objective: string;
+    /** Whether the run is in flight, finished, or errored. */
+    readonly status: AgentRunStatus;
+    /** Epoch ms the delegating assistant message was stamped (for the run clock). */
+    readonly startedAt: number;
+}
+/**
+ * Derive the delegated sub-agent runs from the conversation.
+ *
+ * Walks the messages once: every `task` tool call in an assistant message
+ * becomes a run (named by its `agent` arg, described by its `objective`), and a
+ * later `toolResult` with the matching id resolves its status to done/error.
+ * Runs with no result yet are "running". Pure and order-stable — the same
+ * messages always yield the same list, oldest first.
+ *
+ * @param messages the live conversation (`conductor.messages()`)
+ */
+export declare function deriveAgentRuns(messages: readonly AgentMessage[]): AgentRun[];
+/** What the {@link BackgroundAgents} renders. */
+export interface BackgroundAgentsProps {
+    /** The framework adapter that turns token roles into terminal colours. */
+    readonly theme: InkThemeAdapter;
+    /** The derived sub-agent runs (from {@link deriveAgentRuns}). */
+    readonly runs: readonly AgentRun[];
+    /** Live token spend per run, keyed by run id (the task tool-call id). */
+    readonly tokens?: Readonly<Record<string, number>>;
+    /** Current epoch ms, for the run clock. Defaults to `Date.now()`. */
+    readonly now?: number;
+}
+/**
+ * Render the background-agents panel, or nothing when no run is in flight.
+ *
+ * @param props the theme, the derived runs, and the current time
+ */
+export declare function BackgroundAgents({ theme, runs, tokens, now }: BackgroundAgentsProps): JSX.Element | null;

package/dist/types/console/components/BackgroundAgents.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * BackgroundAgents — pure derivation tests.
+ *
+ * Exercises {@link deriveAgentRuns} against hand-built conversations (no Ink):
+ * `task` tool calls become runs, matched `toolResult` messages resolve their
+ * status, non-task calls are ignored, and unnamed agents fall back to a label.
+ */
+export {};

package/dist/types/console/components/Banner.d.ts

@@ -1,18 +1,30 @@
 /**
- * Banner — the masthead the console renders above the transcript.
+ * Banner — the "IndusCode Saffron" masthead the console renders above the
+ * transcript.
  *
- * The startup chrome the surface mounts once at the top of a session: an
- * original block-letter wordmark rendered in the box-drawing palette and tinted
- * with the accent/signal role, a version + brand line beneath it, and a compact
- * bordered "Session" panel of at-a-glance facts (the bound model id and the
- * working directory). It reads nothing but its props, holds no state, and runs
- * no effects — purely presentational Ink primitives themed through the framework
- * {@link InkThemeAdapter}.
+ * The startup chrome the surface mounts at the top of a session. Its loud
+ * (default) mode has two presentations, switched by {@link BannerProps.started}:
  *
- * The wordmark is the "INDUS CODE" brand masthead rendered in the ANSI-Shadow
- * block-figlet style from the `█ ║ ═ ╔ ╗ ╚ ╝` box-drawing family — the same
- * masthead the shipped console shows, so both surfaces share one identity. The
- * glyph rows are plain data tinted with the accent role at render time.
+ *   - **Welcome card** (fresh session, no messages yet): a bordered card in the
+ *     saffron brand look — a compact `● IndusCode v…` brand label, then two
+ *     columns (left: a personalized greeting above a small block-art robot
+ *     mascot and the bound model / working directory; right: a rotating "getting
+ *     started" tip and the "What's new" notes). The mascot expression and the
+ *     tip rotate per session (seeded once at mount and threaded in via
+ *     {@link BannerProps.variantSeed}), so a new session looks a little different
+ *     each time while staying deterministic for tests.
+ *   - **Startup & Chat masthead** (once the user has sent a message): the
+ *     `➜ dir git:(branch) indus` shell line, the block-letter "INDUS CODE"
+ *     wordmark, the `indus console v…` brand line, the welcome line, and a
+ *     bordered "Session" panel (model + cwd). The conversation itself is rendered
+ *     below the banner by the surface's `MessageList`.
+ *
+ * It reads nothing but its props, holds no state, and runs no effects — purely
+ * presentational Ink primitives themed through the framework
+ * {@link InkThemeAdapter}. The {@link BannerProps.quiet} or
+ * {@link BannerProps.compact} flags collapse all of that to a single compact
+ * header line, still carrying the welcome line, the notices, and a condensed
+ * changelog so nothing important is silently dropped.
  */
 import { type InkThemeAdapter } from "indusagi/react-ink";
 import type { StartupChangelog, StartupMap, StartupNotice } from "../startup";
@@ -26,19 +38,27 @@ export interface BannerProps {
     readonly workspace: string;
     /** The product version shown on the brand line (e.g. the package VERSION). */
     readonly version: string;
+    /**
+     * Whether the conversation has begun (the user has sent at least one message).
+     * When `false` the loud banner is the fresh-session welcome card; when `true`
+     * it becomes the Startup & Chat masthead (wordmark + Session panel) that sits
+     * above the transcript. Has no effect in {@link quiet}/{@link compact} modes.
+     */
+    readonly started?: boolean;
+    /** The active VCS branch (for the masthead shell line), or `null`/absent outside a repo. */
+    readonly branch?: string | null;
     /** Whether to render the extra diagnostics line. */
     readonly verbose?: boolean;
     /**
-     * When set, the big wordmark + Startup Map are suppressed in favour of a
-     * single compact header line. Wired from the verbose / quiet-startup flag.
+     * When set, the welcome card is suppressed in favour of a single compact
+     * header line. Wired from the verbose / quiet-startup flag.
      */
     readonly quiet?: boolean;
     /**
      * When set, the masthead auto-condenses to a single emblem + brand + model
-     * line (the repeat-launch presentation): the user has already seen this
-     * version's full masthead, so the big wordmark is skipped. Distinct from
-     * {@link quiet}, which is the manual suppression toggle; either collapses the
-     * banner, but `compact` keeps the small emblem and the welcome line.
+     * line (the repeat-launch presentation). Distinct from {@link quiet}, which is
+     * the manual suppression toggle; either collapses the banner, but `compact`
+     * keeps the small emblem and the welcome line.
      */
     readonly compact?: boolean;
     /**
@@ -47,15 +67,30 @@ export interface BannerProps {
      */
     readonly name?: string;
     /**
-     * Opt-in static colour-sweep flourish: when set, the wordmark and emblem fill
-     * are tinted along a frozen primary→secondary gradient instead of the flat
-     * accent. The caller is responsible for suppressing it under reduced-motion /
-     * non-TTY; this prop is simply the resolved on/off decision.
+     * Opt-in static colour-sweep flourish (legacy; accepted for call-site
+     * compatibility). The saffron welcome card paints from the theme roles and
+     * does not consume this flag.
      */
     readonly sweep?: boolean;
-    /** The gathered session resources rendered as the Startup Map panel. */
+    /**
+     * The per-session variation seed. Selects which mascot expression + "getting
+     * started" tip the card shows; the same seed always yields the same pair, so a
+     * test pins an exact variant. Absent → the first (seed 0) variant.
+     */
+    readonly variantSeed?: number;
+    /**
+     * Optional override for the "What's new" notes (e.g. sourced from a live
+     * changelog). Absent → the shipped {@link WHATS_NEW} copy.
+     */
+    readonly whatsNew?: readonly string[];
+    /**
+     * The gathered session resources (context docs, skills, prompts). Reserved:
+     * the saffron welcome card shows quick-action chips in place of the old
+     * "Startup Map" panel, so this is accepted for call-site compatibility (and to
+     * keep the gathering machinery wired) but not rendered in the card.
+     */
     readonly startup?: StartupMap;
-    /** Out-of-band lines drawn above the wordmark (errors, warnings, info). */
+    /** Out-of-band lines drawn above the card (errors, warnings, info). */
     readonly notices?: readonly StartupNotice[];
     /** The changelog survey rendered as a "What is new" block on a version bump. */
     readonly changelog?: StartupChangelog;
@@ -63,14 +98,13 @@ export interface BannerProps {
 /**
  * Render the console masthead.
  *
- * In the default (loud) mode this is the two-tone emblem beside the block-letter
- * wordmark, the brand / version line, the personalized welcome line, the
- * optional notices region, the bordered Startup Map, and the changelog block.
- * The {@link BannerProps.quiet} or {@link BannerProps.compact} flags collapse
- * all of that to a single compact header line (emblem glyph + brand + version +
- * model), still carrying the welcome line, the notices, and a condensed
- * changelog so nothing important is silently dropped.
+ * In the default (loud) mode this is the saffron welcome card: a `● IndusCode
+ * v…` brand label and a two-column body (greeting + mascot + model/cwd on the
+ * left, a rotating tip + the "What's new" notes on the right). The
+ * {@link BannerProps.quiet} or {@link BannerProps.compact} flags
+ * collapse all of that to a single compact header line, still carrying the
+ * welcome line, the notices, and a condensed changelog.
  *
- * @param props the wordmark context, version, session facts, and startup chrome
+ * @param props the brand/version context, session facts, and startup chrome
  */
-export declare function Banner({ theme, modelId, workspace, version, verbose, quiet, compact, name, sweep, startup, notices, changelog, }: BannerProps): JSX.Element;
+export declare function Banner({ theme, modelId, workspace, version, started, branch, quiet, compact, name, variantSeed, whatsNew, notices, changelog, }: BannerProps): JSX.Element;

package/dist/types/console/components/welcome.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Welcome-card content & per-session variation — the pure data behind the
+ * "IndusCode Saffron" startup card (the boxed masthead the {@link Banner} draws
+ * in its loud mode).
+ *
+ * This module holds *no* React or Ink: it is the render-agnostic source of the
+ * card's rotating mascot, the rotating "getting started" tip, the static
+ * "what's new" notes, the slash chips, and the small block-art robot mascot
+ * geometry. The banner reads these and paints them through the theme adapter;
+ * the geometry is returned as tone-tagged {@link MascotSegment}s so the banner
+ * maps a tone → a colour role without re-deriving the layout.
+ *
+ * Per-session freshness ("every new session the welcome looks a little
+ * different") is a *pure* selection: {@link pickWelcomeVariant} maps an integer
+ * seed onto one mascot + one tip deterministically, so a test pins an exact
+ * variant while the live surface seeds it once at mount from
+ * {@link randomWelcomeSeed}. Nothing here reads a clock or mutates state — same
+ * seed in, same variant out.
+ */
+/**
+ * One robot-mascot face: the two eye glyphs and the three-cell mouth.
+ *
+ * The face is drawn into a fixed nine-cell-wide rounded head (see
+ * {@link mascotRows}); only the eyes and mouth change between variants, so a
+ * face is just those glyphs plus a human-readable key for tests/logs. Each eye
+ * is exactly one display cell and the mouth exactly three so every face packs
+ * into the same head outline without shifting the columns.
+ */
+export interface MascotFace {
+    /** Stable identifier for the expression (for tests and selection logs). */
+    readonly key: string;
+    /** The left/right eye glyphs (one display cell each). */
+    readonly eyes: readonly [string, string];
+    /** The three-cell mouth glyph row. */
+    readonly mouth: string;
+}
+/**
+ * The rotating mascot expressions, in selection order.
+ *
+ * Each is the same rounded saffron head with dark eyes and a teal mouth — the
+ * expression is the only thing that changes session to session.
+ */
+export declare const MASCOTS: readonly MascotFace[];
+/** A drawn cell's colour intent, mapped to a theme role by the banner. */
+export type MascotTone = "head" | "eye" | "mouth" | "feet";
+/** One painted span of a mascot row: literal text plus its colour intent. */
+export interface MascotSegment {
+    /** The literal glyphs to draw. */
+    readonly text: string;
+    /** Which colour role the banner paints this span in. */
+    readonly tone: MascotTone;
+}
+/**
+ * Lay a {@link MascotFace} out into its drawable rows.
+ *
+ * Returns one array of {@link MascotSegment}s per terminal row of the mascot — a
+ * five-row rounded head (top, eyes, mouth, base, feet). The head outline is the
+ * `head` tone, the eyes the `eye` tone, the mouth the `mouth` tone, and the feet
+ * the `feet` tone; the banner resolves each tone to a concrete colour. Every row
+ * is the same nine-cell width (the feet row is centred under it), so the column
+ * stays rectangular whichever expression is chosen.
+ *
+ * @param face the expression to lay out
+ */
+export declare function mascotRows(face: MascotFace): readonly (readonly MascotSegment[])[];
+/**
+ * The rotating "Tips for getting started" lines.
+ *
+ * One is shown per session (chosen by {@link pickWelcomeVariant}); the pool is
+ * ordinary onboarding guidance so a returning user sees a different nudge each
+ * launch rather than the same line forever.
+ */
+export declare const TIPS: readonly string[];
+/**
+ * The static "What's new" notes shown in the card's right column.
+ *
+ * These are stable per release (the banner can override them from a live
+ * changelog); they describe the most recent user-facing changes.
+ */
+export declare const WHATS_NEW: readonly string[];
+/** The chosen per-session presentation: one mascot face and one tip line. */
+export interface WelcomeVariant {
+    /** The mascot expression to draw this session. */
+    readonly mascot: MascotFace;
+    /** The "getting started" tip to show this session. */
+    readonly tip: string;
+}
+/**
+ * Pick the welcome card's mascot + tip for a session seed.
+ *
+ * Pure and total: the same seed always yields the same variant, and any integer
+ * (including a negative one) lands on a valid mascot and tip. The mascot and the
+ * tip are advanced by different strides of the seed so they do not move in
+ * lock-step — two nearby seeds vary both independently.
+ *
+ * @param seed the per-session seed (e.g. from {@link randomWelcomeSeed})
+ */
+export declare function pickWelcomeVariant(seed: number): WelcomeVariant;
+/**
+ * The PINNED welcome-card variant seed. The card no longer rotates per session
+ * (one stable brand look): seeded with this, {@link pickWelcomeVariant} always
+ * resolves to the clean "focus" mascot (`MASCOTS[0]` — `●  ●` eyes, flat `───`
+ * mouth) + the Shift+Tab tip (`TIPS[2]`). (`12 % MASCOTS.length === 0` → focus;
+ * `Math.trunc(12 / MASCOTS.length) % TIPS.length === 2` → the Shift+Tab tip.) Swap
+ * the mount back to {@link randomWelcomeSeed} to restore per-session rotation.
+ */
+export declare const PINNED_WELCOME_SEED = 12;
+/**
+ * Mint a fresh seed for the current session.
+ *
+ * Impure by design (it reads the RNG), so the live surface calls it *once* at
+ * mount and threads the result into the otherwise-pure banner. Tests never call
+ * this — they pass a fixed seed to {@link pickWelcomeVariant} instead.
+ */
+export declare function randomWelcomeSeed(): number;

package/dist/types/console/components/welcome.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Welcome-card content & variation — pure behavioural tests.
+ *
+ * These exercise the render-agnostic data behind the saffron welcome card
+ * without mounting Ink: the per-session variant selection (deterministic,
+ * total, independent strides) and the mascot geometry (rectangular, tone-tagged,
+ * expression-driven).
+ */
+export {};

package/dist/types/console/contract.d.ts

@@ -60,13 +60,15 @@ export type { SessionConductor, SessionSignal, ConductorState };
  *
  * Named for the time-of-day they evoke rather than a bare light/dark axis, with
  * a daltonized (color-blind-friendly) variant of each:
+ *   - `saffron`     — the IndusCode brand scheme: a warm saffron-on-cream dark
+ *     terminal look with a cool teal accent. The shipped default.
  *   - `midnight`    — a low-luminance scheme for dark terminals.
  *   - `daylight`    — a high-luminance scheme for light terminals.
  *   - `midnight-cb` — the dark scheme re-derived so success vs failure separates
  *     off the red-green axis (success → blue), deuteran/protan-safe.
  *   - `daylight-cb` — the light scheme's color-blind-safe counterpart.
  */
-export type ThemeScheme = "midnight" | "daylight" | "midnight-cb" | "daylight-cb";
+export type ThemeScheme = "saffron" | "midnight" | "daylight" | "midnight-cb" | "daylight-cb";
 /** The default scheme applied before any user preference is loaded. */
 export declare const DEFAULT_SCHEME: ThemeScheme;
 /**

package/dist/types/console/index.d.ts

@@ -26,6 +26,9 @@ export { TerminalConsole } from "./components/TerminalConsole";
 export { Composer, type ComposerProps } from "./components/Composer";
 export { StatusBar, type StatusBarProps } from "./components/StatusBar";
 export { Banner, type BannerProps } from "./components/Banner";
+export { BackgroundAgents, deriveAgentRuns, type BackgroundAgentsProps, type AgentRun, type AgentRunStatus, } from "./components/BackgroundAgents";
+export { AgentsView, type AgentsViewProps } from "./components/AgentsView";
+export { MASCOTS, TIPS, WHATS_NEW, mascotRows, pickWelcomeVariant, randomWelcomeSeed, type MascotFace, type MascotTone, type MascotSegment, type WelcomeVariant, } from "./components/welcome";
 export { gatherStartup, gatherChangelog } from "./startup";
 export type { StartupMap, StartupSection, StartupChangelog, StartupChangelogMode, StartupNotice, StartupNoticeKind, StartupInputs, } from "./startup";
 export { mountConsole, type MountConsoleOptions, type MountResult, } from "./mount";