@sapiom/harness 0.1.5 → 0.2.0

package/dist/shared/types.d.ts

@@ -21,11 +21,27 @@ export declare const HARNESS_PATHS: {
     readonly settings: "~/.sapiom/harness/settings.json";
     /** Generated per-session agent config (claude settings/mcp-config files). */
     readonly generated: "~/.sapiom/harness/generated";
-    /** The bundled example project, seeded lazily by POST /api/sample-project
-     *  (the welcome panel's "Run the sample project") — stable so re-running
-     *  the sample reuses the same copy instead of scattering fresh ones. */
+    /**
+     * Archived session records — one compacted `<harnessSessionId>.json` per
+     * conversation (core/record-archive.ts). Deliberately NOT under `generated`:
+     * that directory is deleted the moment a session's pty exits, and these have
+     * to outlive `events.ndjson`'s 30-day retention, not undercut it.
+     */
+    readonly records: "~/.sapiom/harness/records";
+    /** Where the bundled example project is seeded. Written ONLY by
+     *  `scripts/seed-example.mjs` (demo prep) since the in-app sample action and
+     *  its `POST /api/sample-project` route were removed — the running Studio
+     *  neither seeds nor reads this path, so a directory here is leftover output.
+     *  Kept stable so re-seeding reuses one copy instead of scattering fresh ones. */
     readonly sampleProject: "~/.sapiom/harness/sample-project";
 };
+/**
+ * The file that makes a directory an agent project. Canonical home: three
+ * copies of this literal used to live in core/workspace-watcher.ts,
+ * core/workflow-registry.ts and (now) server/fs.ts, the first of which carried
+ * a "kept in sync with" comment admitting the duplication. Import it.
+ */
+export declare const AGENT_PROJECT_MARKER = "sapiom.json";
 /**
  * Canvas convention: agents write static HTML here, relative to the session
  * cwd. The server watches this directory and serves it at
@@ -42,14 +58,6 @@ export declare const CANVAS_INDEX = ".sapiom/canvas/index.html";
  * pipeline.
  */
 export declare const CANVAS_RENDERS_DIR = ".sapiom/canvas/renders";
-/**
- * Per-workflow enrichment cache lives here (one `<slug>.json` per workflow,
- * same slug scheme as CANVAS_RENDERS_DIR), relative to the session cwd:
- * `{ graph, enrichment, sourceFingerprint, enrichedAt }`. A stale
- * sourceFingerprint keeps the enrichment displayed (with a "stale" chip)
- * until a re-run replaces it — see core/canvas-enrich.ts.
- */
-export declare const CANVAS_CACHE_DIR = ".sapiom/canvas/cache";
 /**
  * Composer image attachments (upload / paste / drag-drop) land here, relative
  * to the session cwd, before their path is relayed into the agent's prompt.
@@ -129,6 +137,16 @@ export interface HarnessSession {
      *  via `PATCH /api/sessions/:id/workflow`; mirrored into
      *  HARNESS_CONTEXT_FILE in the session's cwd so the agent can read it. */
     boundWorkflowPath: string | null;
+    /**
+     * The prior session this one was seeded from (portable continue — see
+     * core/rehydration.ts), when a brief was ACTUALLY produced and delivered.
+     * Null/absent otherwise, including when the client asked to rehydrate from
+     * an id our event log holds nothing for: this field is the record of what
+     * happened, not of what was requested, so the UI can never present an
+     * empty-handed fresh session as a continuation. Absent on sessions
+     * persisted by builds from before this existed.
+     */
+    rehydratedFrom?: string | null;
     /**
      * `status === "running"` only means the pty is alive — the agent's TUI
      * can still be sitting on a blocking prompt (most commonly: "trust this
@@ -144,7 +162,23 @@ export interface HarnessSession {
      */
     ready: boolean;
 }
-/** A resumable past session discovered from agent transcripts or our registry. */
+/**
+ * What resuming a past session would ACTUALLY do — resolved server-side
+ * against the agent's own conversation store, never guessed from whether we
+ * happen to hold an `agentSessionId`.
+ *
+ * - `agent-resume`: the agent still holds this conversation, so
+ *   `HarnessAdapter.resume()` reattaches to it for real.
+ * - `rehydrate`: the agent does NOT hold it. Most commonly a session that
+ *   ended before its first prompt — Claude Code writes no transcript at all
+ *   for those, and Codex writes no rollout file (see CodexAdapter's
+ *   `detectBlockingPrompt` for the same rule from the other direction). The
+ *   conversation is unrecoverable from the agent; the only honest options are
+ *   a fresh session in the same directory, or (once H3 lands) replaying our
+ *   own recorded context into one.
+ */
+export type SessionResumeMode = "agent-resume" | "rehydrate";
+/** A past session discovered from agent transcripts or our registry. */
 export interface SessionSummary {
     /** Back-reference to our session when the registry tracked it (source "registry"). */
     harnessSessionId?: string;
@@ -154,6 +188,14 @@ export interface SessionSummary {
     title: string;
     lastActiveAt: string;
     source: "registry" | "transcript";
+    /**
+     * Whether this row can genuinely be handed back to the agent — verified
+     * against the agent's own store by `GET /api/sessions/history`, for BOTH
+     * row sources. Holding an `agentSessionId` is not evidence of anything:
+     * we capture it from the SessionStart hook, which fires long before the
+     * agent has a conversation worth resuming.
+     */
+    resumeMode: SessionResumeMode;
     /**
      * Git branch the session was last active on, when the transcript records it.
      * The strongest within-directory differentiator between otherwise-similar
@@ -167,7 +209,26 @@ export interface SessionSummary {
      * full read (see the claude-code adapter's full-scan size cap).
      */
     messageCount?: number;
+    /**
+     * Number of human prompts (turns) the harness itself recorded for this
+     * session — from the event store's byte-offset index, or from the archived
+     * record once the events behind it have been swept. Exact and cheap at any
+     * file size — unlike {@link messageCount}, which the claude-code adapter
+     * leaves undefined above its full-scan cap. Undefined when the harness has
+     * neither events nor an archived record for the session (a transcript the
+     * Studio never ran). Prefer this over messageCount when both are present.
+     */
+    turnCount?: number;
 }
+/**
+ * What an adapter reports having FOUND — everything in a `SessionSummary`
+ * except `resumeMode`. Deciding what resuming a row would do is the server's
+ * job (`GET /api/sessions/history`), so the adapter contract deliberately
+ * can't express it: that's what kept transcript rows hardcoded to
+ * un-resumable while registry rows were hardcoded to resumable, each wrong in
+ * the opposite direction.
+ */
+export type PastSessionRecord = Omit<SessionSummary, "resumeMode">;
 export interface DoctorCheck {
     name: string;
     ok: boolean;
@@ -205,7 +266,31 @@ export interface LaunchOpts {
     /** Only consulted by `launchTask` — hard cap on agent turns
      *  (`--max-turns`), so a bounded task can't run away. */
     maxTurns?: number;
+    /**
+     * Set by the launch-opts builder when this launch's context was seeded from
+     * a prior session's recorded events (portable continue — see
+     * core/rehydration.ts). Carries the id the brief was built from. Adapters
+     * ignore it entirely; `SessionManager.create()` copies it onto
+     * {@link HarnessSession.rehydratedFrom} so the UI can say whether the
+     * continue really carried context instead of implying it did.
+     */
+    rehydratedFrom?: string;
 }
+/**
+ * How a harness receives the rehydration brief for a continued session.
+ *
+ * - `launch-flag`: the adapter puts `LaunchOpts.systemPromptFile`'s contents in
+ *   front of the agent at spawn time (claude-code's `--append-system-prompt`,
+ *   codex's `developer_instructions`), so composing the brief into that file is
+ *   the whole delivery.
+ * - `post-ready-injection`: the harness has no such flag, so the brief is sent
+ *   through the ordinary input path once the session reports `ready` — gated on
+ *   readiness so it is never written into a TUI sitting on a trust prompt.
+ *
+ * See `systemPromptDeliveryFor` (core/rehydration.ts) for why the absent case
+ * resolves to the fallback rather than the flag.
+ */
+export type SystemPromptDelivery = "launch-flag" | "post-ready-injection";
 /**
  * One implementation per supported coding agent. Implementations must be
  * side-effect free until `launch`/`resume` specs are actually spawned.
@@ -218,8 +303,34 @@ export interface HarnessAdapter {
     resume(agentSessionId: string, opts: LaunchOpts): SpawnSpec;
     /** How analytics events are sourced for this harness. */
     eventSource: "hooks" | "transcript-tail";
-    /** Resumable sessions for a directory (agent-side history). */
-    listPastSessions(cwd: string): Promise<SessionSummary[]>;
+    /**
+     * Whether `launch`/`resume` actually put `LaunchOpts.systemPromptFile` in
+     * front of the agent. Declared rather than inferred, because the alternative
+     * — assuming every adapter honours the field — silently drops a rehydration
+     * brief for one that doesn't. Omitted resolves to `post-ready-injection`
+     * (see `systemPromptDeliveryFor` in core/rehydration.ts).
+     */
+    systemPromptDelivery?: SystemPromptDelivery;
+    /** Past sessions this agent recorded for a directory (agent-side history).
+     *  Reports what it found; `resumeMode` is the server's call — see
+     *  {@link PastSessionRecord}. */
+    listPastSessions(cwd: string): Promise<PastSessionRecord[]>;
+    /**
+     * Does this agent's OWN conversation store still hold `agentSessionId` for
+     * `cwd` — i.e. would `resume()` reattach to a real conversation rather than
+     * dying on startup?
+     *
+     * This exists because holding an `agentSessionId` proves nothing: we capture
+     * it from the SessionStart hook, which fires before the user has submitted
+     * anything, and an agent that never received a prompt writes no transcript
+     * at all. Without this check, one in three history rows was a Resume button
+     * guaranteed to fail with `No conversation found with session ID: …`.
+     *
+     * Contract: **never throws**. A missing, unreadable, or empty store is
+     * `false` — a resumability probe must not be able to break the history
+     * endpoint or `resume()`'s pre-flight.
+     */
+    canResume(agentSessionId: string, cwd: string): Promise<boolean>;
     /**
      * Best-effort scrollback check for this harness's own known blocking
      * prompts (e.g. "trust this directory?"), for harnesses whose real
@@ -337,38 +448,38 @@ export type BusMessage = {
     type: "session.activity";
     harnessSessionId: string;
     at: string;
-};
-/** Per-step cost summary from the spend endpoint. */
-export interface RunStepSpend {
-    name: string;
-    totalUsd: string;
-    entryCount: number;
 }
-/** Full spend summary for one execution, keyed by executionId. */
-export interface RunSpend {
-    executionId: string;
-    totalUsd: string;
-    settleState: string;
-    byStep: RunStepSpend[];
-}
-/**
- * One billable capability call within a run — the per-call drill-down behind a
- * step's cost ("why is this step costly"). Derived from the transactions
- * endpoint. Deliberately provider-AGNOSTIC: `capability` is a generic label
- * ("LLM", "sandbox", "web search") mapped server-side from the operation, so
- * neither the browser nor this file ever carries the upstream provider/model
- * name. Token counts are intentionally absent — the platform does not record
- * per-call tokens for gateway LLM calls (see SAP ticket for the backend work).
- */
-export interface RunCall {
-    /** Step this call is attributed to (workflowStepName ?? capability op). */
-    stepName: string;
-    /** Provider-agnostic capability label, e.g. "LLM" / "sandbox" / "web search". */
+/**
+ * Auth state changed — fired after a successful sign-in (`POST
+ * /api/auth/start`) or sign-out (`POST /api/auth/disconnect`). The SPA
+ * should refetch `/api/auth/status` (or `/api/state`) on receipt to update
+ * its auth UI without a full page reload.
+ */
+ | {
+    type: "auth.changed";
+    authenticated: boolean;
+    organizationName: string | null;
+};
+/**
+ * One capability call a step made during the run. Capability-scoped and
+ * provider-agnostic: `capability` is a dotted capability id (e.g.
+ * `web.search`, `models.coding.run`) — never a provider or model name.
+ * `stubUsed` records whether this call was served by a supplied stub instead
+ * of a real capability call, which is the single most load-bearing fact when
+ * explaining a local (offline) run. Optional fields are ABSENT (not null)
+ * when the source does not carry the value — honest absence.
+ */
+export interface StepCall {
+    /** Dotted capability id (provider-agnostic — never a provider/model name). */
     capability: string;
-    /** The capability operation, e.g. "generate" / "create" / "execute". */
-    op: string;
-    /** Captured USD for this single call. */
-    usd: string;
+    /** True when a supplied stub served this call rather than the real capability. */
+    stubUsed?: boolean;
+    /** The arguments the call was made with, when the source carries them. Any
+     *  JSON shape; ABSENT (not null) otherwise. */
+    args?: unknown;
+    /** The value the call returned — the served stub value for a local run, or
+     *  the capability result for a prod run. ABSENT when the source has no result. */
+    result?: unknown;
 }
 /**
  * A step's render status, folded from the raw projection step status into the
@@ -378,17 +489,15 @@ export interface RunCall {
  */
 export type StepStatus = "pending" | "running" | "passed" | "failed";
 /** One step as the canvas renders it — status plus the deterministically
- *  derived cost/latency/error/log slice. Optional fields are ABSENT (not
+ *  derived latency/error/log slice. Optional fields are ABSENT (not
  *  `undefined`/`0`) when the decoded projection carries no value — honest
- *  absence, matching the SDK's cost-is-nullable philosophy. */
+ *  absence. The inspector surfaces logs, latency, and pass/fail only. */
 export interface StepView {
     /** Stable id for keyed rendering — the OTel span id, else a step-order key. */
     id: string;
     /** Human step label (the projection's stepName). */
     name: string;
     status: StepStatus;
-    /** Captured USD for this step; absent when the read carries no cost. */
-    costUsd?: number;
     /** finishedAt − startedAt in ms; absent while running or on bad timestamps. */
     latencyMs?: number;
     /** Terminal error message; present only for a failed step that recorded one. */
@@ -396,13 +505,59 @@ export interface StepView {
     /** Tail-preserving, character-capped executor log text — the debug-macro
      *  context source (trimmed further before injection). Absent when no logs. */
     logSlice?: string;
+    /** The resolved input the step actually ran on, when the source carries it
+     *  (populated by local stub runs today; a production run projection may
+     *  expose it in future). Any JSON shape. ABSENT — never `null`/`{}` — when
+     *  the source has no per-step input, so the inspector shows nothing rather
+     *  than fabricating a payload. */
+    input?: unknown;
+    /** The value the step produced, on the same honest-absence terms as
+     *  {@link StepView.input}: present only when the source captured a real
+     *  output, absent otherwise (a still-running or output-less step shows no
+     *  Output block). Any JSON shape. */
+    output?: unknown;
+    /** The capability calls this step made during the run, in call order. Each
+     *  entry is capability-scoped and provider-agnostic. Absent (never `[]`)
+     *  when the source records no call information for this step — honest
+     *  absence, mirroring `input`/`output`. A local run populates this from
+     *  the stub client's per-call sink; a prod run leaves it absent when the
+     *  step projection does not carry dotted-capability call records. */
+    calls?: StepCall[];
+}
+/** A supplied stub key that no capability call ever matched in its step — almost
+ *  always a typo or the wrong path form. Surfaced read-only in the inspector so a
+ *  no-op mock (a stub that silently served nothing) is visible instead of a
+ *  mystery. Mirrors agent-core's `UnusedStub` (consumed as-is). */
+export interface UnusedStubView {
+    step: string;
+    key: string;
 }
 /** A whole run as the canvas renders it. `status` is the run lifecycle folded
- *  to the four states the UI distinguishes; `steps` is order-preserving. */
+ *  to the four states the UI distinguishes; `steps` is order-preserving.
+ *
+ *  Stub fields are RUN-LEVEL and honest-absence: they are set only by
+ *  {@link renderLocalRun} for an offline stub run (prod runs from renderRunState
+ *  never carry them), and only when they carry real signal. A local run is
+ *  stub-served by construction — every `ctx.sapiom.*` call resolves from a stub —
+ *  so `stubbed` is the honest per-run truth the inspector marks each executed
+ *  step with (agent-core records no per-CALL stub attribution, so the chip lives
+ *  at the granularity the trace actually supports). `unusedStubs`/`stubWarnings`
+ *  come from the run's terminal NDJSON summary and are ABSENT (not `[]`) when
+ *  empty, so the read-only notice renders nothing when there is nothing wrong. */
 export interface RunView {
     executionId: string;
     status: "running" | "completed" | "failed" | "cancelled";
     steps: StepView[];
+    /** True when this run was served entirely by stub capabilities (an offline
+     *  local run). Absent for real (prod / local-backend) runs. Drives the
+     *  per-step "stubbed" chip. */
+    stubbed?: boolean;
+    /** Supplied stub keys that matched no capability call this run (likely a typo
+     *  / wrong path). Absent when none — never an empty array. */
+    unusedStubs?: UnusedStubView[];
+    /** Human-readable warnings about stub values that matched a key but had the
+     *  wrong shape (the silent-wrong-data trap). Absent when none. */
+    stubWarnings?: string[];
 }
 /** One entry in the adapter registry, as the SPA sees it (GET /api/harnesses). */
 export interface HarnessEntry {
@@ -429,7 +584,7 @@ export interface HarnessEntry {
  * See the collector README section in packages/harness/src/core/collector/
  * for the full surface-"ui" contract.
  */
-export type UiEventName = "prompt.submitted" | "session.switched" | "macro.invoked" | "visualize.triggered" | "consent.changed" | "session.created" | "skill.viewed" | "skill.used" | "mcp.install";
+export type UiEventName = "prompt.submitted" | "session.switched" | "macro.invoked" | "visualize.triggered" | "consent.changed" | "session.created" | "mcp.install";
 export interface UiTrackRequest {
     /** Dot-canonical event name — one of the UiEventName literals. */
     event: UiEventName;
@@ -442,7 +597,7 @@ export interface UiTrackRequest {
     harnessSessionId?: string;
 }
 export declare const ANALYTICS_SCHEMA_VERSION = 1;
-export type AnalyticsEventType = "session.start" | "prompt.submitted" | "tool.call" | "turn.completed" | "session.end" | "session.switched" | "macro.invoked" | "visualize.triggered" | "consent.changed" | "session.created" | "skill.viewed" | "skill.used" | "mcp.install";
+export type AnalyticsEventType = "session.start" | "prompt.submitted" | "tool.call" | "turn.completed" | "session.end" | "session.switched" | "macro.invoked" | "visualize.triggered" | "consent.changed" | "session.created" | "mcp.install";
 /**
  * The normalized event — the shape that (with opt-in) is batched to the
  * remote collector and always appended to events.ndjson locally.
@@ -450,9 +605,17 @@ export type AnalyticsEventType = "session.start" | "prompt.submitted" | "tool.ca
  */
 export interface AnalyticsEvent {
     eventId: string;
-    /** Per-harnessSessionId monotonic counter from 1 — ordering + loss detection. */
+    /**
+     * Per-harnessSessionId counter from 1, for loss detection *within one
+     * process epoch* — NOT a session-lifetime ordering key. The counter lives
+     * in the server's memory (core/collector/seq.ts), so it restarts at 1 on
+     * every harness boot and on every fresh pty for the same session: a real
+     * resumed session reads 1, 2 then 1, 1, 1. A reset means "new epoch", never
+     * "events lost". Anything that orders events must sort by `(ts, seq)` —
+     * see core/session-record.ts.
+     */
     seq: number;
-    /** ISO-8601, client clock. Use seq (not ts) for intra-session ordering. */
+    /** ISO-8601, client clock. Primary ordering key; `seq` only breaks ties. */
     ts: string;
     /** Sapiom user id from auth; null when not logged in. */
     userId: string | null;
@@ -487,11 +650,158 @@ export interface CollectorBatch {
     context: CollectorContext;
     events: AnalyticsEvent[];
 }
+/** One tool invocation inside a turn, from a `tool.call` event. */
+export interface SessionRecordToolCall {
+    /** Tool name as the agent reported it; null when the event omitted one. */
+    name: string | null;
+    /** Stringified tool input (JSON for structured inputs), possibly truncated. */
+    input: string | null;
+    /** Truncated stringified tool result — see {@link responseTruncated}. */
+    responseSummary: string | null;
+    /** True when the stored response hit the collector's size cap and the real
+     *  output was longer. The missing bytes are not recoverable from our log. */
+    responseTruncated: boolean;
+    /** ISO-8601 timestamp of the `tool.call` event. */
+    at: string;
+}
+/** One prompt→response turn. A turn opens on `prompt.submitted` and closes on
+ *  `turn.completed`; tool calls in between attach to it. */
+export interface SessionRecordTurn {
+    /** 1-based ordinal in the record — stable for deep links and test asserts. */
+    index: number;
+    /**
+     * The human prompt that opened the turn. Null for a turn our events imply
+     * but never saw a prompt for: tool calls or a completion that arrived with
+     * no open turn (a session whose recording started mid-turn, or an agent-
+     * initiated turn). Rendered as an explicit "no recorded prompt", never faked.
+     */
+    prompt: string | null;
+    /** ISO-8601 timestamp of the opening `prompt.submitted`; null when absent. */
+    promptAt: string | null;
+    toolCalls: SessionRecordToolCall[];
+    /**
+     * The assistant's final message for the turn. This is the Stop hook's LAST
+     * assistant message only — narration *between* tool calls is not in our
+     * event stream (see core/collector/transcript.ts). Null when the harness
+     * never captured one (Codex's rollout has no equivalent field).
+     */
+    assistantText: string | null;
+    /** Model that produced the turn, when the transcript backfill supplied it. */
+    model: string | null;
+    usage: {
+        inputTokens: number | null;
+        outputTokens: number | null;
+    } | null;
+    /** ISO-8601 timestamp of the closing `turn.completed`; null when open. */
+    completedAt: string | null;
+    /** True when no `turn.completed` ever closed this turn — the session was
+     *  killed mid-turn, or a new prompt superseded it. */
+    incomplete: boolean;
+}
+/**
+ * A known, structural gap in a reconstructed record. Codes (not prose) so the
+ * UI owns the wording and the set can grow without breaking older clients.
+ *
+ * - `truncated-tool-output`: at least one tool result hit the collector's size
+ *   cap; the full output is not in our log.
+ * - `assistant-narration-gap`: a turn has tool calls plus a final assistant
+ *   message, so whatever the agent said *between* those calls is missing.
+ * - `missing-assistant-text`: a turn completed with no assistant text at all
+ *   (Codex, whose rollout carries no equivalent of the Stop hook's field).
+ * - `incomplete-final-turn`: the last turn never completed — the session
+ *   ended mid-turn.
+ * - `compacted-archive`: the record was read from its archived copy, whose
+ *   tool inputs and results are clipped to keep it bounded (see
+ *   core/record-archive.ts). The conversation is whole; the tool payloads
+ *   inside it are excerpts.
+ * - `dropped-early-turns`: the archived copy kept only the most recent turns —
+ *   `turns` holds fewer of them than `turnCount` says happened.
+ */
+export type SessionRecordLimitation = "truncated-tool-output" | "assistant-narration-gap" | "missing-assistant-text" | "incomplete-final-turn" | "compacted-archive" | "dropped-early-turns";
+/** `GET /api/sessions/:id/record` response. */
+export interface SessionRecord {
+    /** The harness session this record was folded from. When several harness
+     *  sessions share one agent session (a resumed conversation), this is the
+     *  first of them and `mergedSessionIds` lists them all. */
+    harnessSessionId: string;
+    /** Every harnessSessionId folded into this record, in first-seen order. */
+    mergedSessionIds: string[];
+    /** The agent's own session id, when our events carried one. */
+    agentSessionId: string | null;
+    harness: HarnessKind;
+    /** cwd from the `session.start` event; null when it never recorded one. */
+    cwd: string | null;
+    /** ISO-8601 of the earliest event in the record. */
+    startedAt: string | null;
+    /** ISO-8601 of the `session.end` event; null for a session that never
+     *  reported ending (killed, or crashed). */
+    endedAt: string | null;
+    turns: SessionRecordTurn[];
+    /**
+     * Human prompts in the CONVERSATION — `turns.filter(t => t.prompt != null)
+     * .length` for a record folded from events, and still that same count for an
+     * archived record whose oldest turns were dropped to fit its size cap. It
+     * describes what happened, not what survived, so a history row's turn count
+     * doesn't change when its events get swept; `dropped-early-turns` in
+     * {@link limitations} is what says `turns` holds fewer than this.
+     */
+    turnCount: number;
+    /** Events folded into this record (including ones no turn field shows).
+     *  Like {@link turnCount}, counted before any archive compaction. */
+    eventCount: number;
+    /** Always true. Present on the wire so no client can mistake a record for a
+     *  verbatim replay of what the user saw in their terminal. */
+    reconstructed: true;
+    /**
+     * ISO-8601 of when this record was written to the durable archive
+     * (`~/.sapiom/harness/records/`), or null when it was folded from the live
+     * event log. Non-null therefore means "this is the archived copy": bounded,
+     * compacted, and — unlike the events — still here after the analytics sink's
+     * retention sweep. The UI says so where the user reads it.
+     */
+    archivedAt: string | null;
+    limitations: SessionRecordLimitation[];
+}
 export interface CreateSessionRequest {
     cwd: string;
     harness: HarnessKind;
     /** Profile id; omit for default. */
     profile?: string;
+    /**
+     * Portable continue: seed this fresh session with a reconstruction of a
+     * prior one instead of asking the vendor to reattach. Accepts either a
+     * `harnessSessionId` or the agent's own session id — whichever the history
+     * row carries — and is what a `resumeMode: "rehydrate"` row posts.
+     *
+     * Best-effort by contract: an id our event log holds nothing for still
+     * creates the session, with `HarnessSession.rehydratedFrom` left null so the
+     * caller can tell that no context came across. Refusing instead would block
+     * the only thing still possible for that row (a fresh session in the same
+     * directory) on a summary that was never going to exist.
+     */
+    rehydrateFrom?: string;
+}
+/**
+ * `POST /api/sessions/adopt` body — takes a transcript-only history row (one
+ * the registry never tracked, `SessionSummary.harnessSessionId` absent) into
+ * the registry and immediately resumes it, so a row whose transcript really is
+ * there reattaches to the agent instead of quietly starting a fresh session.
+ *
+ * The server re-verifies `resumeMode` itself via `HarnessAdapter.canResume`
+ * before registering anything — a client claim is never taken on trust, and a
+ * `rehydrate` row 409s with `SESSION_NOT_RESUMEABLE` rather than leaving a
+ * phantom record behind.
+ */
+export interface AdoptSessionRequest {
+    /** The agent's own conversation id, as reported by `GET /sessions/history`. */
+    agentSessionId: string;
+    harness: HarnessKind;
+    cwd: string;
+    /** Display title carried over from the history row. */
+    title: string;
+    /** When the transcript was last touched — becomes the adopted record's
+     *  `createdAt`/`lastActiveAt` so history keeps sorting it where it was. */
+    lastActiveAt: string;
 }
 /** Inject text into the session pty (used by macros and the Visualize button). */
 export interface InjectInputRequest {
@@ -585,6 +895,18 @@ export interface AppState {
     /** The directory the CLI was launched against — the SPA prefills the
      *  new-session modal with this instead of recentDirs[0]. */
     launchDir: string;
+    /**
+     * The HOST's default parent directory for NEW agent projects, before the
+     * user's `projectRoot` setting overrides it. The server supplies it because
+     * only the server knows which host it is running under: the Electron app
+     * passes `<launchDir>/projects` (keeping user code out of the state
+     * directory's own listing), while the CLI leaves it as `launchDir` — the
+     * developer `cd`'d somewhere on purpose.
+     *
+     * Optional so existing AppState constructors (tests, mocks) stay valid; the
+     * SPA falls back to `launchDir`, which is the CLI behaviour anyway.
+     */
+    defaultProjectRoot?: string;
     /** Harness kinds with a working binary on PATH at CLI boot (from doctor()),
      *  in default-preference order — `[0]` is what the auto-created boot
      *  session used. Optional: omitted by callers that construct AppState
@@ -613,14 +935,152 @@ export interface AppState {
      *  then falls back to the SDK's own default host. */
     agentsBaseUrl?: string;
 }
-/** `POST /api/sample-project` response — the seeded (or reused) example. */
-export interface SampleProjectSeedResponse {
-    /** Directory to open a session in — contains the project + its canvas. */
-    root: string;
-    /** Absolute path of the scaffolded example project inside `root`. */
-    projectDir: string;
-    /** False when an already-seeded copy was reused as-is. */
-    created: boolean;
+/**
+ * The counts a complexity band was derived from, so a surface can explain the
+ * band instead of just asserting it. Mirrors core's `TemplateComplexityBasisDto`.
+ */
+export interface TemplateComplexityBasis {
+    /** Steps declared `kind: 'llm'` — each is a judgment point. */
+    llmSteps: number;
+    /** Model steps feeding directly into another model step (compounding variance). */
+    chainedLlmSteps: number;
+    /** Media-generation capabilities (image/video). */
+    mediaCapabilities: number;
+    capabilityCount: number;
+    stepCount: number;
+    /** Largest number of outgoing targets on any one step. */
+    maxFanOut: number;
+}
+/**
+ * How involved a template is, on a 1–5 band derived by core from the template's
+ * declared shape. `score` and `label` are redundant on purpose: the score orders
+ * and the label reads. A surface renders one of them, never a raw weighted sum —
+ * that would invite false precision on what is explicitly a rough estimate.
+ *
+ * Owned by core's `workflows/template-complexity.ts`. The Studio computes
+ * nothing: whether the band is derived (today) or authored (SAP-2086/2087), this
+ * type is unchanged and this surface reads whatever core serves.
+ */
+export interface TemplateComplexity {
+    /** 1–5, monotonic in `label`. */
+    score: number;
+    /** `Minimal` | `Simple` | `Moderate` | `Involved` | `Advanced`. A loose string
+     *  for the same reason `category` is: the band vocabulary is owned upstream. */
+    label: string;
+    basis: TemplateComplexityBasis;
+}
+/**
+ * A gallery card, relayed verbatim from core's `GET /v1/workflows/templates`
+ * (`TemplateSummaryDto`). The Studio does NOT own this taxonomy — the registry
+ * in the public sapiom-js repo does, and core derives the complexity band from
+ * each template's declared shape. Fields are carried through untouched so the
+ * Studio's list and the dashboard's Template library can never disagree.
+ */
+export interface TemplateSummary {
+    id: string;
+    name: string;
+    description: string;
+    tags: string[];
+    /** Registry outcome-axis id (`starter`, `revenue-marketing`, …), or null for a
+     *  template predating the field. A loose string on purpose: the taxonomy is
+     *  owned upstream, so an unrecognised id buckets as uncategorised rather than
+     *  dropping the card. */
+    category: string | null;
+    /** What starts a run (`on-demand` | `scheduled` | `on-webhook` | `on-event`),
+     *  or null when undeclared. */
+    cadence: string | null;
+    stepCount: number;
+    /** Dotted catalog capability ids (e.g. `web.search`). */
+    capabilities: string[];
+    /**
+     * How involved the template is. Replaced an estimated per-run cost that core
+     * could only compute for 5 of 26 templates; a band is defined for every one.
+     *
+     * NULLABLE HERE THOUGH CORE TYPES IT REQUIRED, and that is not belt-and-braces.
+     * The Studio is a published npm package: an old copy can point at any backend,
+     * and a fresh copy can point at a backend that predates the field (a local
+     * stack, a self-hosted one, prod before the promotion). Typing it required
+     * would put an unguarded dereference in the row renderer and take out the whole
+     * dialog. One row degrading to an em dash is the right failure.
+     *
+     * Note the em dash means something new: it used to be "no cost estimate
+     * exists", the majority case; it now means "this response predates the band" —
+     * a different claim wearing the same glyph, and one nobody should ever see
+     * against a current backend.
+     */
+    complexity: TemplateComplexity | null;
+}
+/**
+ * One step of a template's declared graph (core's `DefinitionStepDto` subset the
+ * detail pane renders).
+ *
+ * `kind`/`sublabel` come from `classifyStepKind` — the SAME precedence the canvas
+ * applies to a real definition — so the preview and the post-clone canvas agree.
+ * There is deliberately no `terminal` boolean: the four transition kinds
+ * (`continue`/`pause`/`terminate`/`fail`) do not collapse into one, and pretending
+ * they do renders a fail-only sink as a green success exit.
+ */
+export interface TemplateStepView {
+    name: string;
+    description: string | null;
+    capabilities: string[];
+    /** Canvas node kind: `entry` | `step` | `pause` | `terminal-success` | `terminal-warn`. */
+    kind: string;
+    /** One-line role, e.g. `entry`, `step · can also fail`, `terminal · success`. */
+    sublabel: string;
+}
+/** One edge of a template's declared graph (core's `DefinitionTransitionDto`). */
+export interface TemplateTransitionView {
+    from: string;
+    to: string;
+    /** The signal a `pause` edge waits for; null for a plain `continue`. */
+    label: string | null;
+    /** `cross` for a pause edge (as the canvas draws it), else continue flow. */
+    kind: "continue" | "pause";
+}
+/**
+ * `GET /api/templates/:id` — the summary plus the rich manifest the detail pane
+ * renders. Core expands the registry's hand-authored step list into the same
+ * graph shapes a real definition uses, so the preview and the post-clone canvas
+ * are the same vocabulary.
+ */
+export interface TemplateDetailView extends TemplateSummary {
+    /** Prose from the co-located `template.json`; null when the manifest omits it. */
+    whatItDoes: string | null;
+    /** Path inside the sapiom-js repo the fork is seeded from. */
+    sourcePath: string | null;
+    steps: TemplateStepView[];
+    transitions: TemplateTransitionView[];
+    author: {
+        name: string;
+        url: string | null;
+    } | null;
+    useCases: string[];
+    /** Markdown. */
+    notes: string | null;
+    examples: Array<{
+        title: string | null;
+        input: unknown;
+        output: unknown;
+    }>;
+    /** Credentials the template needs supplied before a deployed run works. */
+    requiredSecrets: Array<{
+        key: string;
+        label: string;
+        description: string | null;
+    }>;
+}
+/**
+ * `GET /api/templates` response. `source` tells the SPA whether it is looking at
+ * the live catalog or the offline fallback, so the dialog can say so instead of
+ * silently presenting two entries as the whole gallery — the failure mode this
+ * endpoint exists to fix.
+ */
+export interface TemplateListResponse {
+    templates: TemplateSummary[];
+    source: "live" | "fallback";
+    /** Why the live fetch was not used, when `source` is `fallback`. */
+    reason?: "signed-out" | "unreachable";
 }
 export interface HarnessSettings {
     telemetryOptIn: boolean;
@@ -632,10 +1092,43 @@ export interface HarnessSettings {
      * Persisted so the notice never appears again after the first dismiss.
      */
     telemetryNoticeDismissed?: boolean;
+    /**
+     * Where NEW agent projects are created (the add-workspace template and idea
+     * doors). Absent until the user changes it, in which case the host default
+     * (`AppState.defaultProjectRoot`) applies.
+     *
+     * Deliberately the same value the door itself edits: changing the root while
+     * creating a project saves it as the default, so there is one place to set it
+     * rather than a door value that silently diverges from a settings value.
+     */
+    projectRoot?: string;
+    /**
+     * Opt-in: periodically fold a live session's record into a ≤500-word rolling
+     * summary (see core/rolling-summary.ts), which a later portable continue
+     * reads to explain what the session was *for* rather than only what it last
+     * did. Off by default because it spends tokens on a background LLM call the
+     * user never asked for. With it off, briefs degrade to last-N-turns.
+     */
+    rollingSummary?: boolean;
 }
 export interface FsDirEntry {
     name: string;
     path: string;
+    /**
+     * Whether this directory directly contains AGENT_PROJECT_MARKER.
+     *
+     * Load-bearing, not decorative: without it a picker cannot tell an agent
+     * project from any other folder, so it has to offer every escape hatch
+     * (register / scaffold / template / bulk-scan / install-MCP) at all times —
+     * which is exactly what made the old add-workspace dialog unusable. With it,
+     * those become outcomes of what we found rather than permanent options.
+     *
+     * Only ONE level deep, matching this endpoint's contract. A `false` here does
+     * not mean the subtree is empty of projects — a container folder whose
+     * children are projects reports `false` (the rail's recursive scan is the
+     * thing that answers "anything under here?").
+     */
+    hasAgentProject: boolean;
 }
 /**
  * GET /api/fs/list?path= response — directories only, one level deep.
@@ -684,11 +1177,10 @@ export interface MacroDef {
         kind: "open-url";
         url: string;
     }
-    /** Force refresh of the bound workflow's canvas: invalidates the
-     *  extraction + enrichment caches, re-renders the deterministic diagram
-     *  instantly, and re-spawns the bounded AI enrichment task (see
-     *  core/canvas-enrich.ts) — no pty involved. A cheap no-op when the
-     *  session is unbound. */
+    /** Refresh of the bound workflow's canvas: invalidates the extraction
+     *  cache and re-renders the fully deterministic diagram (structure +
+     *  derived annotations, no LLM, no user token) — no pty involved. A cheap
+     *  no-op when the session is unbound. */
      | {
         kind: "render-canvas";
     };