@gobing-ai/ts-ai-runner 0.4.18 → 0.4.19

package/README.md

@@ -291,6 +291,57 @@ const gitBlock = getGitContext('/workspace/spur');
 // "Git context:\nbranch: feat/team-mode\ndirty: 3 files"
 ```
 
+## Session Affinity (run-scoped sessions)
+
+`PromptOptions` carries two additive fields for pinning or isolating sessions:
+
+- `sessionId?: string` — resume a specific prior session when the agent supports resume-by-id.
+- `sessionDir?: string` — isolate session storage into a caller-owned directory (durable).
+
+When either is set, the shim selects the **run-scoped session path** and **never** emits an unscoped
+global continue/last-session flag. This prevents a pipeline hop from attaching to the host's
+interactive session (ADR-047).
+
+**Precedence (R5):**
+
+1. `sessionId` or `sessionDir` set → pin/isolate path; bare `continue` is ignored for global-last.
+2. else `continue === true` → legacy resume-last (only where the agent allows it).
+3. else → fresh open.
+
+**Capability query (R2):** consult `getAgentSessionCapability(agent)` rather than inventing per-agent
+argv. It reports `supportsResumeById` and `supportsSessionDir`.
+
+```ts
+import { getAgentSessionCapability, getAgentShim } from '@gobing-ai/ts-ai-runner';
+
+const cap = getAgentSessionCapability('omp'); // { supportsResumeById: true, supportsSessionDir: true }
+const { args } = getAgentShim('omp').getPromptCommand({
+    input: '',
+    sessionDir: '.spur/run/r1/agent-sessions/omp',
+    sessionId: 'abc123',
+});
+// args: ['-p', '', '--session-dir', '.spur/run/r1/...', '-r', 'abc123', '--mode', 'text']
+```
+
+**Shim / capability matrix:**
+
+| Agent | `supportsResumeById` | `supportsSessionDir` | sessionDir flag | sessionId resume flag | Legacy continue |
+| ----- | -------------------- | -------------------- | --------------- | --------------------- | --------------- |
+| omp | ✓ | ✓ | `--session-dir <dir>` | `-r <id>` | `-c` |
+| pi | ✓ | ✓ | `--session-dir <dir>` | `-r <id>` | `-c` |
+| claude | ✓ | ✗ (ignored) | — | `--resume <id>` | `--continue` |
+| codex | ✗ | ✗ (ignored) | — | degrade → fresh `exec` | `exec resume --last` |
+| agy | ✓ | ✗ (ignored) | — | `--conversation <id>` | `--continue` |
+| grok | ✓ | ✗ (ignored) | — | `--resume <id>` | `-c` |
+
+**Degrade rule:** when `sessionDir`/`sessionId` is set and the agent lacks resume-by-id or a
+session-store flag, the shim opens **fresh in isolation** (or plain fresh) — never bare global
+continue/last. codex, which has no one-shot resume-by-id, always degrades to a fresh `exec`.
+
+**Durable vs ephemeral (R4):** for omp/pi, setting `sessionDir` implies a durable session — the shim
+omits `--no-session` so a session file is written and discoverable. The legacy fresh path (no session
+fields, `continue` false) keeps `--no-session`.
+
 ## Observability
 
 `AiRunner` and `TeamOrchestrator` emit typed events when an `EventBus<AgentEvents>` is provided:

package/dist/agents/shims.d.ts

@@ -15,6 +15,19 @@ export interface PromptOptions {
     input?: string;
     /** Continue the previous session if the agent supports it. */
     continue?: boolean;
+    /**
+     * Pin a specific session to resume, when the agent supports resume-by-id
+     * (see {@link getAgentSessionCapability}). Setting `sessionId` or `sessionDir`
+     * selects the run-scoped session path and suppresses any unscoped global
+     * continue/last-session flag (ADR-047 precedence R5).
+     */
+    sessionId?: string;
+    /**
+     * Isolate session storage into this directory (where the agent supports it).
+     * Implies a durable session: agents with a session-store flag (omp/pi) must not
+     * emit `--no-session` when this is set, so the session file is discoverable.
+     */
+    sessionDir?: string;
     /** Model identifier passed through to the agent CLI. */
     model?: string;
     /** Output mode passed through to the agent CLI. */
@@ -64,6 +77,15 @@ export interface AgentShim {
 }
 /** All bundled agent shims keyed by canonical agent name. */
 export declare const AGENT_SHIMS: Readonly<Record<AgentName, AgentShim>>;
+/** Session-affinity capability for one coding agent (ADR-047). */
+export interface AgentSessionCapability {
+    /** Can resume a specific prior session by id (e.g. `-r <id>` / `--resume <id>`). */
+    readonly supportsResumeById: boolean;
+    /** Can isolate session storage into a caller-supplied directory. */
+    readonly supportsSessionDir: boolean;
+}
+/** Query a bundled agent's session-affinity capability by canonical name. */
+export declare function getAgentSessionCapability(agent: AgentName): AgentSessionCapability;
 /** Tier-1 auto-selection priority. Deprecated ids are excluded. */
 export declare const TIER1_PRIORITY: readonly AgentName[];
 /** Display order for doctor and list commands. */

package/dist/agents/shims.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shims.d.ts","sourceRoot":"","sources":["../../src/agents/shims.ts"],"names":[],"mappings":"AAEA,gEAAgE;AAChE,MAAM,MAAM,SAAS,GACf,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,IAAI,GACJ,UAAU,GACV,iBAAiB,GACjB,UAAU,GACV,QAAQ,GACR,KAAK,GACL,MAAM,CAAC;AAEb,0CAA0C;AAC1C,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAEzC,mEAAmE;AACnE,MAAM,WAAW,WAAW;IACxB,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,4CAA4C;AAC5C,MAAM,WAAW,aAAa;IAC1B,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,KAAK,CAAC,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjE;AAED,2EAA2E;AAC3E,MAAM,WAAW,gBAAgB;IAC7B,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,CAAC;CACnC;AAED,qDAAqD;AACrD,MAAM,WAAW,SAAS;IACtB,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,+BAA+B;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC;IACrB,sFAAsF;IACtF,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,wFAAwF;IACxF,QAAQ,CAAC,UAAU,CAAC,EAAE,gBAAgB,CAAC;IACvC,oCAAoC;IACpC,cAAc,IAAI,WAAW,CAAC;IAC9B,yCAAyC;IACzC,iBAAiB,IAAI,WAAW,CAAC;IACjC,yCAAyC;IACzC,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,WAAW,CAAC;IACtD,8DAA8D;IAC9D,cAAc,IAAI,WAAW,GAAG,IAAI,CAAC;CACxC;AAuLD,6DAA6D;AAC7D,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,CAW9D,CAAC;AAEF,mEAAmE;AACnE,eAAO,MAAM,cAAc,EAAE,SAAS,SAAS,EAS9C,CAAC;AAEF,kDAAkD;AAClD,eAAO,MAAM,aAAa,EAAE,SAAS,SAAS,EAW7C,CAAC;AAEF,6CAA6C;AAC7C,eAAO,MAAM,YAAY,EAAE,WAAW,CAAC,SAAS,CAAyB,CAAC;AAU1E;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAQrE;AAED;mEACmE;AACnE,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAElD;AAED,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAMxD"}
+{"version":3,"file":"shims.d.ts","sourceRoot":"","sources":["../../src/agents/shims.ts"],"names":[],"mappings":"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"}

package/dist/agents/shims.js

@@ -7,8 +7,16 @@ const claudeShim = {
     getVersionCommand: () => ({ command: 'claude', args: ['--version'] }),
     getPromptCommand: (options) => {
         const args = ['-p', options.input ?? ''];
-        if (options.continue === true)
+        const hasSession = options.sessionId !== undefined || options.sessionDir !== undefined;
+        if (hasSession) {
+            // Session/pin path — never emit --continue. Claude has no session-dir
+            // flag; sessionDir is ignored (best-effort isolate).
+            if (options.sessionId !== undefined)
+                args.push('--resume', options.sessionId);
+        }
+        else if (options.continue === true) {
             args.push('--continue');
+        }
         if (options.model !== undefined)
             args.push('--model', options.model);
         args.push('--output-format', options.mode ?? 'text');
@@ -23,10 +31,13 @@ const codexShim = {
     getHelpCommand: () => ({ command: 'codex', args: ['--help'] }),
     getVersionCommand: () => ({ command: 'codex', args: ['--version'] }),
     getPromptCommand: (options) => {
-        if (options.continue === true && options.input !== undefined) {
+        const hasSession = options.sessionId !== undefined || options.sessionDir !== undefined;
+        // Session/pin path degrades to a fresh `exec` — codex has no reliable
+        // one-shot resume-by-id, so never `exec resume --last` (no global last).
+        if (options.continue === true && !hasSession && options.input !== undefined) {
             throw new Error('Codex resume mode does not accept a new prompt');
         }
-        const args = options.continue === true ? ['exec', 'resume', '--last'] : ['exec', options.input ?? ''];
+        const args = options.continue === true && !hasSession ? ['exec', 'resume', '--last'] : ['exec', options.input ?? ''];
         if (options.model !== undefined)
             args.push('-m', options.model);
         if ((options.mode ?? 'text') === 'json')
@@ -61,11 +72,17 @@ const piShim = {
     getVersionCommand: () => ({ command: 'pi', args: ['--version'] }),
     getPromptCommand: (options) => {
         const args = [];
-        if (options.continue !== true)
+        const hasSession = options.sessionId !== undefined || options.sessionDir !== undefined;
+        // Session/pin path: durable — never ephemeral --no-session, never global -c.
+        if (!hasSession && options.continue !== true)
             args.push('--no-session');
         args.push('-p', options.input ?? '');
-        if (options.continue === true)
+        if (!hasSession && options.continue === true)
             args.push('-c');
+        if (options.sessionDir !== undefined)
+            args.push('--session-dir', options.sessionDir);
+        if (options.sessionId !== undefined)
+            args.push('-r', options.sessionId);
         if (options.model !== undefined)
             args.push('--model', options.model);
         args.push('--mode', options.mode ?? 'text');
@@ -105,8 +122,16 @@ const antigravityCliShim = {
     getVersionCommand: () => ({ command: 'agy', args: ['--version'] }),
     getPromptCommand: (options) => {
         const args = ['-p', options.input ?? ''];
-        if (options.continue === true)
+        const hasSession = options.sessionId !== undefined || options.sessionDir !== undefined;
+        if (hasSession) {
+            // Session/pin path — never emit --continue. agy has no session-dir flag;
+            // sessionDir is ignored (best-effort isolate).
+            if (options.sessionId !== undefined)
+                args.push('--conversation', options.sessionId);
+        }
+        else if (options.continue === true) {
             args.push('--continue');
+        }
         if (options.model !== undefined)
             args.push('--model', options.model);
         return { command: 'agy', args };
@@ -154,11 +179,17 @@ const ompShim = {
     getVersionCommand: () => ({ command: 'omp', args: ['--version'] }),
     getPromptCommand: (options) => {
         const args = [];
-        if (options.continue !== true)
+        const hasSession = options.sessionId !== undefined || options.sessionDir !== undefined;
+        // Session/pin path: durable — never ephemeral --no-session, never global -c.
+        if (!hasSession && options.continue !== true)
             args.push('--no-session');
         args.push('-p', options.input ?? '');
-        if (options.continue === true)
+        if (!hasSession && options.continue === true)
             args.push('-c');
+        if (options.sessionDir !== undefined)
+            args.push('--session-dir', options.sessionDir);
+        if (options.sessionId !== undefined)
+            args.push('-r', options.sessionId);
         if (options.model !== undefined)
             args.push('--model', options.model);
         args.push('--mode', options.mode ?? 'text');
@@ -180,8 +211,16 @@ const grokShim = {
     getVersionCommand: () => ({ command: 'grok', args: ['--version'] }),
     getPromptCommand: (options) => {
         const args = ['-p', options.input ?? ''];
-        if (options.continue === true)
+        const hasSession = options.sessionId !== undefined || options.sessionDir !== undefined;
+        if (hasSession) {
+            // Session/pin path — never emit -c. grok has no session-dir flag;
+            // sessionDir is ignored (best-effort isolate).
+            if (options.sessionId !== undefined)
+                args.push('--resume', options.sessionId);
+        }
+        else if (options.continue === true) {
             args.push('-c');
+        }
         if (options.model !== undefined)
             args.push('-m', options.model);
         // Grok has no `text` format; map ai-runner OutputMode `text` → `plain`.
@@ -204,6 +243,34 @@ export const AGENT_SHIMS = {
     omp: ompShim,
     grok: grokShim,
 };
+/**
+ * Session-affinity capability metadata per agent. Callers must consult this
+ * instead of inventing per-agent argv: when `sessionDir`/`sessionId` are set,
+ * `supportsResumeById` decides resume-by-id vs fresh-degrade, and
+ * `supportsSessionDir` decides whether `sessionDir` is honored (ADR-047 R2).
+ *
+ * Agents not in the six-agent affinity matrix default to no resume-by-id and no
+ * session-dir — they get the isolated-fresh / no-resume degrade.
+ */
+const AGENT_SESSION_CAPABILITY = {
+    omp: { supportsResumeById: true, supportsSessionDir: true },
+    pi: { supportsResumeById: true, supportsSessionDir: true },
+    claude: { supportsResumeById: true, supportsSessionDir: false },
+    // codex resume is interactive-only (`exec resume` picker); no one-shot
+    // resume-by-id and no session-dir — degrades to fresh exec.
+    codex: { supportsResumeById: false, supportsSessionDir: false },
+    'antigravity-cli': { supportsResumeById: true, supportsSessionDir: false },
+    grok: { supportsResumeById: true, supportsSessionDir: false },
+    // Non-matrix agents: conservative default (isolated-fresh / no-resume).
+    gemini: { supportsResumeById: false, supportsSessionDir: false },
+    opencode: { supportsResumeById: false, supportsSessionDir: false },
+    openclaw: { supportsResumeById: false, supportsSessionDir: false },
+    hermes: { supportsResumeById: false, supportsSessionDir: false },
+};
+/** Query a bundled agent's session-affinity capability by canonical name. */
+export function getAgentSessionCapability(agent) {
+    return AGENT_SESSION_CAPABILITY[agent];
+}
 /** Tier-1 auto-selection priority. Deprecated ids are excluded. */
 export const TIER1_PRIORITY = [
     'pi',

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-ai-runner",
-    "version": "0.4.18",
+    "version": "0.4.19",
     "description": "@gobing-ai/ts-ai-runner — Coding-agent shims, detection, doctor checks, and prompt execution.",
     "keywords": [
         "typescript",
@@ -47,12 +47,12 @@
         "release": "echo 'Manual publish is disabled. Releases go through GitHub Actions via Trusted Publishing — push a tag: git tag @gobing-ai/ts-ai-runner-v<version> && git push --tags' && exit 1"
     },
     "dependencies": {
-        "@gobing-ai/ts-infra": "^0.4.18",
-        "@gobing-ai/ts-runtime": "^0.4.18"
+        "@gobing-ai/ts-infra": "^0.4.19",
+        "@gobing-ai/ts-runtime": "^0.4.19"
     },
     "devDependencies": {
         "@types/bun": "1.3.14",
-        "@gobing-ai/ts-db": "^0.4.18"
+        "@gobing-ai/ts-db": "^0.4.19"
     },
     "publishConfig": {
         "access": "public"

package/src/agents/shims.ts

@@ -30,6 +30,19 @@ export interface PromptOptions {
     input?: string;
     /** Continue the previous session if the agent supports it. */
     continue?: boolean;
+    /**
+     * Pin a specific session to resume, when the agent supports resume-by-id
+     * (see {@link getAgentSessionCapability}). Setting `sessionId` or `sessionDir`
+     * selects the run-scoped session path and suppresses any unscoped global
+     * continue/last-session flag (ADR-047 precedence R5).
+     */
+    sessionId?: string;
+    /**
+     * Isolate session storage into this directory (where the agent supports it).
+     * Implies a durable session: agents with a session-store flag (omp/pi) must not
+     * emit `--no-session` when this is set, so the session file is discoverable.
+     */
+    sessionDir?: string;
     /** Model identifier passed through to the agent CLI. */
     model?: string;
     /** Output mode passed through to the agent CLI. */
@@ -84,7 +97,14 @@ const claudeShim: AgentShim = {
     getVersionCommand: () => ({ command: 'claude', args: ['--version'] }),
     getPromptCommand: (options) => {
         const args = ['-p', options.input ?? ''];
-        if (options.continue === true) args.push('--continue');
+        const hasSession = options.sessionId !== undefined || options.sessionDir !== undefined;
+        if (hasSession) {
+            // Session/pin path — never emit --continue. Claude has no session-dir
+            // flag; sessionDir is ignored (best-effort isolate).
+            if (options.sessionId !== undefined) args.push('--resume', options.sessionId);
+        } else if (options.continue === true) {
+            args.push('--continue');
+        }
         if (options.model !== undefined) args.push('--model', options.model);
         args.push('--output-format', options.mode ?? 'text');
         return { command: 'claude', args };
@@ -99,10 +119,14 @@ const codexShim: AgentShim = {
     getHelpCommand: () => ({ command: 'codex', args: ['--help'] }),
     getVersionCommand: () => ({ command: 'codex', args: ['--version'] }),
     getPromptCommand: (options) => {
-        if (options.continue === true && options.input !== undefined) {
+        const hasSession = options.sessionId !== undefined || options.sessionDir !== undefined;
+        // Session/pin path degrades to a fresh `exec` — codex has no reliable
+        // one-shot resume-by-id, so never `exec resume --last` (no global last).
+        if (options.continue === true && !hasSession && options.input !== undefined) {
             throw new Error('Codex resume mode does not accept a new prompt');
         }
-        const args = options.continue === true ? ['exec', 'resume', '--last'] : ['exec', options.input ?? ''];
+        const args =
+            options.continue === true && !hasSession ? ['exec', 'resume', '--last'] : ['exec', options.input ?? ''];
         if (options.model !== undefined) args.push('-m', options.model);
         if ((options.mode ?? 'text') === 'json') args.push('--json');
         return { command: 'codex', args };
@@ -135,9 +159,13 @@ const piShim: AgentShim = {
     getVersionCommand: () => ({ command: 'pi', args: ['--version'] }),
     getPromptCommand: (options) => {
         const args: string[] = [];
-        if (options.continue !== true) args.push('--no-session');
+        const hasSession = options.sessionId !== undefined || options.sessionDir !== undefined;
+        // Session/pin path: durable — never ephemeral --no-session, never global -c.
+        if (!hasSession && options.continue !== true) args.push('--no-session');
         args.push('-p', options.input ?? '');
-        if (options.continue === true) args.push('-c');
+        if (!hasSession && options.continue === true) args.push('-c');
+        if (options.sessionDir !== undefined) args.push('--session-dir', options.sessionDir);
+        if (options.sessionId !== undefined) args.push('-r', options.sessionId);
         if (options.model !== undefined) args.push('--model', options.model);
         args.push('--mode', options.mode ?? 'text');
         return { command: 'pi', args };
@@ -175,7 +203,14 @@ const antigravityCliShim: AgentShim = {
     getVersionCommand: () => ({ command: 'agy', args: ['--version'] }),
     getPromptCommand: (options) => {
         const args = ['-p', options.input ?? ''];
-        if (options.continue === true) args.push('--continue');
+        const hasSession = options.sessionId !== undefined || options.sessionDir !== undefined;
+        if (hasSession) {
+            // Session/pin path — never emit --continue. agy has no session-dir flag;
+            // sessionDir is ignored (best-effort isolate).
+            if (options.sessionId !== undefined) args.push('--conversation', options.sessionId);
+        } else if (options.continue === true) {
+            args.push('--continue');
+        }
         if (options.model !== undefined) args.push('--model', options.model);
         return { command: 'agy', args };
     },
@@ -223,9 +258,13 @@ const ompShim: AgentShim = {
     getVersionCommand: () => ({ command: 'omp', args: ['--version'] }),
     getPromptCommand: (options) => {
         const args: string[] = [];
-        if (options.continue !== true) args.push('--no-session');
+        const hasSession = options.sessionId !== undefined || options.sessionDir !== undefined;
+        // Session/pin path: durable — never ephemeral --no-session, never global -c.
+        if (!hasSession && options.continue !== true) args.push('--no-session');
         args.push('-p', options.input ?? '');
-        if (options.continue === true) args.push('-c');
+        if (!hasSession && options.continue === true) args.push('-c');
+        if (options.sessionDir !== undefined) args.push('--session-dir', options.sessionDir);
+        if (options.sessionId !== undefined) args.push('-r', options.sessionId);
         if (options.model !== undefined) args.push('--model', options.model);
         args.push('--mode', options.mode ?? 'text');
         return { command: 'omp', args };
@@ -247,7 +286,14 @@ const grokShim: AgentShim = {
     getVersionCommand: () => ({ command: 'grok', args: ['--version'] }),
     getPromptCommand: (options) => {
         const args = ['-p', options.input ?? ''];
-        if (options.continue === true) args.push('-c');
+        const hasSession = options.sessionId !== undefined || options.sessionDir !== undefined;
+        if (hasSession) {
+            // Session/pin path — never emit -c. grok has no session-dir flag;
+            // sessionDir is ignored (best-effort isolate).
+            if (options.sessionId !== undefined) args.push('--resume', options.sessionId);
+        } else if (options.continue === true) {
+            args.push('-c');
+        }
         if (options.model !== undefined) args.push('-m', options.model);
         // Grok has no `text` format; map ai-runner OutputMode `text` → `plain`.
         const format = (options.mode ?? 'text') === 'json' ? 'json' : 'plain';
@@ -271,6 +317,44 @@ export const AGENT_SHIMS: Readonly<Record<AgentName, AgentShim>> = {
     grok: grokShim,
 };
 
+/** Session-affinity capability for one coding agent (ADR-047). */
+export interface AgentSessionCapability {
+    /** Can resume a specific prior session by id (e.g. `-r <id>` / `--resume <id>`). */
+    readonly supportsResumeById: boolean;
+    /** Can isolate session storage into a caller-supplied directory. */
+    readonly supportsSessionDir: boolean;
+}
+
+/**
+ * Session-affinity capability metadata per agent. Callers must consult this
+ * instead of inventing per-agent argv: when `sessionDir`/`sessionId` are set,
+ * `supportsResumeById` decides resume-by-id vs fresh-degrade, and
+ * `supportsSessionDir` decides whether `sessionDir` is honored (ADR-047 R2).
+ *
+ * Agents not in the six-agent affinity matrix default to no resume-by-id and no
+ * session-dir — they get the isolated-fresh / no-resume degrade.
+ */
+const AGENT_SESSION_CAPABILITY: Readonly<Record<AgentName, AgentSessionCapability>> = {
+    omp: { supportsResumeById: true, supportsSessionDir: true },
+    pi: { supportsResumeById: true, supportsSessionDir: true },
+    claude: { supportsResumeById: true, supportsSessionDir: false },
+    // codex resume is interactive-only (`exec resume` picker); no one-shot
+    // resume-by-id and no session-dir — degrades to fresh exec.
+    codex: { supportsResumeById: false, supportsSessionDir: false },
+    'antigravity-cli': { supportsResumeById: true, supportsSessionDir: false },
+    grok: { supportsResumeById: true, supportsSessionDir: false },
+    // Non-matrix agents: conservative default (isolated-fresh / no-resume).
+    gemini: { supportsResumeById: false, supportsSessionDir: false },
+    opencode: { supportsResumeById: false, supportsSessionDir: false },
+    openclaw: { supportsResumeById: false, supportsSessionDir: false },
+    hermes: { supportsResumeById: false, supportsSessionDir: false },
+};
+
+/** Query a bundled agent's session-affinity capability by canonical name. */
+export function getAgentSessionCapability(agent: AgentName): AgentSessionCapability {
+    return AGENT_SESSION_CAPABILITY[agent];
+}
+
 /** Tier-1 auto-selection priority. Deprecated ids are excluded. */
 export const TIER1_PRIORITY: readonly AgentName[] = [
     'pi',