specrails-core 6.4.0 → 6.5.0

package/dist/agent-runtime/session/testing/fixture-replayer.d.ts

@@ -0,0 +1,41 @@
+import type { ProcessSpawner, ProcessSpec } from '../drivers/common/process.js';
+/** One recorded transcript row (see the spike harness in the OpenSpec change). */
+export interface FixtureRow {
+    t: number;
+    dir: 'in' | 'out' | 'ctl';
+    json?: Record<string, unknown> | null;
+    raw?: string;
+}
+export declare function loadFixture(file: string): FixtureRow[];
+export interface ReplaySession {
+    readonly spec: ProcessSpec;
+    /** Lines the driver wrote to stdin, parsed. */
+    readonly written: Array<Record<string, unknown>>;
+    readonly inputEnded: boolean;
+    readonly terminated: boolean;
+    /** Resolves when the replay is blocked waiting for the driver, or finished. */
+    idle(): Promise<void>;
+}
+/**
+ * Replays a recorded provider transcript as a ProcessSpawner:
+ * - `out` rows are emitted in order (time compressed);
+ * - before passing an `in` row, replay waits until the driver wrote a line,
+ *   then maps recorded ids/uuids to the ones the driver used;
+ * - a `ctl kill` row waits for `terminate()` (output after it is what the
+ *   provider printed while stopping); `closeStdin` waits for `endInput()`;
+ * - after the last row the process stays alive until terminated, like a
+ *   resident provider, unless the transcript recorded a clean exit.
+ */
+export declare class FixtureReplayer {
+    private readonly rows;
+    private readonly options;
+    readonly sessions: ReplaySession[];
+    constructor(rows: FixtureRow[], options?: {
+        exitAtEnd?: boolean;
+    });
+    static fromFile(file: string, options?: {
+        exitAtEnd?: boolean;
+    }): FixtureReplayer;
+    get last(): ReplaySession;
+    readonly spawner: ProcessSpawner;
+}

package/dist/agent-runtime/session/testing/fixture-replayer.js

@@ -0,0 +1,172 @@
+import { readFileSync } from 'node:fs';
+export function loadFixture(file) {
+    return readFileSync(file, 'utf8').split('\n').filter((line) => line.trim()).map((line) => JSON.parse(line));
+}
+/** Fields whose recorded values are replaced by the values the driver actually wrote. */
+const REMAPPED = ['id', 'uuid', 'command_uuid'];
+/**
+ * Replays a recorded provider transcript as a ProcessSpawner:
+ * - `out` rows are emitted in order (time compressed);
+ * - before passing an `in` row, replay waits until the driver wrote a line,
+ *   then maps recorded ids/uuids to the ones the driver used;
+ * - a `ctl kill` row waits for `terminate()` (output after it is what the
+ *   provider printed while stopping); `closeStdin` waits for `endInput()`;
+ * - after the last row the process stays alive until terminated, like a
+ *   resident provider, unless the transcript recorded a clean exit.
+ */
+export class FixtureReplayer {
+    rows;
+    options;
+    sessions = [];
+    constructor(rows, options = {}) {
+        this.rows = rows;
+        this.options = options;
+    }
+    static fromFile(file, options) {
+        return new FixtureReplayer(loadFixture(file), options);
+    }
+    get last() {
+        const session = this.sessions.at(-1);
+        if (!session)
+            throw new Error('fixture replayer: nothing spawned');
+        return session;
+    }
+    spawner = (spec, handlers) => {
+        const rows = this.rows;
+        const ids = new Map();
+        const written = [];
+        let inputsSeen = 0;
+        let index = 0;
+        let inputOpen = true;
+        let terminated = false;
+        let exit = null;
+        let resolveExit;
+        const exited = new Promise((resolve) => { resolveExit = resolve; });
+        let idleWaiters = [];
+        let blocked = false;
+        const exitAtEnd = this.options.exitAtEnd ?? false;
+        const remap = (value) => {
+            if (Array.isArray(value))
+                return value.map(remap);
+            if (value && typeof value === 'object') {
+                return Object.fromEntries(Object.entries(value).map(([key, inner]) => [key,
+                    REMAPPED.includes(key) && ids.has(JSON.stringify(inner)) ? ids.get(JSON.stringify(inner)) : remap(inner)]));
+            }
+            return value;
+        };
+        const finish = (result) => {
+            if (exit)
+                return;
+            exit = result;
+            blocked = true;
+            resolveExit(result);
+            flushIdle();
+        };
+        const flushIdle = () => { const waiters = idleWaiters; idleWaiters = []; for (const waiter of waiters)
+            waiter(); };
+        const step = () => {
+            if (exit)
+                return;
+            blocked = false;
+            while (index < rows.length) {
+                const row = rows[index];
+                if (row.dir === 'in') {
+                    if (written.length <= inputsSeen) {
+                        blocked = true;
+                        flushIdle();
+                        return;
+                    }
+                    const actual = written[inputsSeen];
+                    for (const key of REMAPPED) {
+                        const recorded = row.json?.[key];
+                        if (recorded !== undefined && actual[key] !== undefined)
+                            ids.set(JSON.stringify(recorded), actual[key]);
+                    }
+                    inputsSeen += 1;
+                    index += 1;
+                    continue;
+                }
+                if (row.dir === 'ctl') {
+                    const control = row.json ?? {};
+                    if ('kill' in control) {
+                        if (!terminated) {
+                            blocked = true;
+                            flushIdle();
+                            return;
+                        }
+                        index += 1;
+                        continue;
+                    }
+                    if ('closeStdin' in control) {
+                        if (inputOpen) {
+                            blocked = true;
+                            flushIdle();
+                            return;
+                        }
+                        index += 1;
+                        continue;
+                    }
+                    if ('end' in control) {
+                        const match = /exit code=(\S+) sig=(\S+)/.exec(String(control.end));
+                        const code = match && match[1] !== 'null' ? Number(match[1]) : null;
+                        const signal = match && match[2] !== 'null' ? match[2] : null;
+                        // A harness timeout means the real process was still alive: stay resident.
+                        if (terminated || exitAtEnd || (signal !== 'SIGKILL' && signal !== 'SIGTERM')) {
+                            finish({ exitCode: code, signal });
+                            return;
+                        }
+                        index += 1;
+                        continue;
+                    }
+                    index += 1;
+                    continue;
+                }
+                index += 1;
+                if (row.json)
+                    handlers.onLine(JSON.stringify(remap(row.json)));
+                else if (row.raw)
+                    handlers.onLine(row.raw);
+                setImmediate(step);
+                return;
+            }
+            if (terminated || exitAtEnd)
+                finish({ exitCode: terminated ? null : 0, signal: terminated ? 'SIGTERM' : null });
+            else {
+                blocked = true;
+                flushIdle();
+            }
+        };
+        const session = {
+            spec,
+            written,
+            get inputEnded() { return !inputOpen; },
+            get terminated() { return terminated; },
+            idle: () => (blocked || exit ? Promise.resolve() : new Promise((resolve) => { idleWaiters.push(resolve); })),
+        };
+        this.sessions.push(session);
+        setImmediate(step);
+        return {
+            pid: 4242,
+            exited,
+            write(line) {
+                if (!inputOpen || exit)
+                    return false;
+                written.push(JSON.parse(line));
+                if (blocked)
+                    setImmediate(step);
+                return true;
+            },
+            endInput() {
+                inputOpen = false;
+                if (blocked)
+                    setImmediate(step);
+            },
+            terminate() {
+                terminated = true;
+                if (blocked)
+                    setImmediate(step);
+                return exited;
+            },
+        };
+    };
+}

package/dist/agent-runtime/session/testing/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Test kit for hosts and driver authors (package export `./agent-runtime/session/testing`).
+ * Framework-free: usable from any test runner.
+ */
+export { DRIVER_CONFORMANCE, type ConformanceCheck, type ConformanceHarness } from './driver-conformance.js';
+export { FixtureReplayer, loadFixture, type FixtureRow, type ReplaySession } from './fixture-replayer.js';
+export { MemoryJournal } from './memory-journal.js';
+export { FakeClock, SequentialIds } from './fake-clock.js';
+export { ScriptedDriverFactory, ScriptedDriverSession, catalogOf, descriptor } from './scripted-driver.js';

package/dist/agent-runtime/session/testing/index.js

@@ -0,0 +1,9 @@
+/**
+ * Test kit for hosts and driver authors (package export `./agent-runtime/session/testing`).
+ * Framework-free: usable from any test runner.
+ */
+export { DRIVER_CONFORMANCE } from './driver-conformance.js';
+export { FixtureReplayer, loadFixture } from './fixture-replayer.js';
+export { MemoryJournal } from './memory-journal.js';
+export { FakeClock, SequentialIds } from './fake-clock.js';
+export { ScriptedDriverFactory, ScriptedDriverSession, catalogOf, descriptor } from './scripted-driver.js';

package/dist/agent-runtime/session/testing/memory-journal.d.ts

@@ -0,0 +1,27 @@
+import type { SessionEvent, SessionEventEnvelope } from '../domain/events.js';
+import { type SessionSnapshot } from '../domain/snapshot.js';
+import type { UsageBaseline } from '../domain/usage.js';
+import type { AppendOptions, SessionJournal, SessionRecord, SessionSummary } from '../ports.js';
+/**
+ * In-memory SessionJournal with the same contract as the SQLite adapter:
+ * gap-free sequences, atomic appends, baselines stored with their events.
+ * `failNextAppend` simulates a failed transaction (nothing becomes visible).
+ */
+export declare class MemoryJournal implements SessionJournal {
+    private readonly sessions;
+    private readonly baselines;
+    failNextAppend: Error | null;
+    createSession(record: SessionRecord): void;
+    getSession(sessionId: string): SessionRecord | null;
+    append(sessionId: string, events: SessionEvent[], options?: AppendOptions): SessionEventEnvelope[];
+    read(sessionId: string, afterSeq: number, limit: number): {
+        events: SessionEventEnvelope[];
+        hasMore: boolean;
+    };
+    snapshot(sessionId: string): SessionSnapshot | null;
+    list(filter: 'open' | 'closed' | 'all'): SessionSummary[];
+    baseline(providerRef: string): UsageBaseline | null;
+    /** Test helper: every committed event of a session. */
+    events(sessionId: string): SessionEventEnvelope[];
+    private require;
+}

package/dist/agent-runtime/session/testing/memory-journal.js

@@ -0,0 +1,70 @@
+import { emptySnapshot, foldEvents } from '../domain/snapshot.js';
+/**
+ * In-memory SessionJournal with the same contract as the SQLite adapter:
+ * gap-free sequences, atomic appends, baselines stored with their events.
+ * `failNextAppend` simulates a failed transaction (nothing becomes visible).
+ */
+export class MemoryJournal {
+    sessions = new Map();
+    baselines = new Map();
+    failNextAppend = null;
+    createSession(record) {
+        if (this.sessions.has(record.sessionId))
+            throw new Error(`Session ${record.sessionId} exists`);
+        this.sessions.set(record.sessionId, { record: { ...record }, events: [], snapshot: emptySnapshot(record.sessionId) });
+    }
+    getSession(sessionId) {
+        return this.sessions.get(sessionId)?.record ?? null;
+    }
+    append(sessionId, events, options) {
+        const entry = this.require(sessionId);
+        if (this.failNextAppend) {
+            const error = this.failNextAppend;
+            this.failNextAppend = null;
+            throw error;
+        }
+        const envelopes = events.map((event, index) => ({ sessionId, seq: entry.snapshot.lastSeq + index + 1, event: structuredClone(event) }));
+        const snapshot = foldEvents(entry.snapshot, envelopes);
+        entry.events.push(...envelopes);
+        entry.snapshot = snapshot;
+        if (options?.baseline)
+            this.baselines.set(options.baseline.providerRef, { ...options.baseline.value });
+        return envelopes.map((envelope) => structuredClone(envelope));
+    }
+    read(sessionId, afterSeq, limit) {
+        const all = this.require(sessionId).events.filter((envelope) => envelope.seq > afterSeq);
+        return { events: structuredClone(all.slice(0, limit)), hasMore: all.length > limit };
+    }
+    snapshot(sessionId) {
+        const entry = this.sessions.get(sessionId);
+        return entry ? structuredClone(entry.snapshot) : null;
+    }
+    list(filter) {
+        return [...this.sessions.values()]
+            .filter(({ snapshot }) => filter === 'all' || snapshot.status === filter)
+            .map(({ record, snapshot }) => ({
+            sessionId: record.sessionId,
+            driver: record.driver,
+            model: snapshot.model,
+            status: snapshot.status,
+            phase: snapshot.phase,
+            lastSeq: snapshot.lastSeq,
+            createdAt: record.createdAt,
+            metadata: { ...record.metadata },
+        }));
+    }
+    baseline(providerRef) {
+        const value = this.baselines.get(providerRef);
+        return value ? { ...value } : null;
+    }
+    /** Test helper: every committed event of a session. */
+    events(sessionId) {
+        return structuredClone(this.require(sessionId).events);
+    }
+    require(sessionId) {
+        const entry = this.sessions.get(sessionId);
+        if (!entry)
+            throw new Error(`Unknown session ${sessionId}`);
+        return entry;
+    }
+}

package/dist/agent-runtime/session/testing/scripted-driver.d.ts

@@ -0,0 +1,30 @@
+import type { DriverCapabilities, DriverDescriptor } from '../domain/types.js';
+import type { CloseReason, DriverCatalog, DriverEvent, DriverEventSink, DriverFactory, DriverInput, DriverOpenSpec, DriverSession } from '../ports.js';
+export declare function descriptor(id: string, capabilities?: Partial<DriverCapabilities>): DriverDescriptor;
+/** One opened provider process, driven by the test through `emit`. */
+export declare class ScriptedDriverSession implements DriverSession {
+    readonly spec: DriverOpenSpec;
+    private readonly sink;
+    readonly sent: DriverInput[];
+    readonly calls: string[];
+    closed: CloseReason | null;
+    /** What `stopSubagents` resolves with. */
+    stopResult: string[] | 'process';
+    /** Events emitted while closing (e.g. Claude's stopped/killed notifications on SIGTERM). */
+    onClose: DriverEvent[];
+    constructor(spec: DriverOpenSpec, sink: DriverEventSink);
+    emit(...events: DriverEvent[]): void;
+    send(input: DriverInput): Promise<void>;
+    interrupt(): Promise<void>;
+    stopSubagents(ids?: string[]): Promise<string[] | 'process'>;
+    close(reason: CloseReason): Promise<void>;
+}
+export declare class ScriptedDriverFactory implements DriverFactory {
+    readonly descriptor: DriverDescriptor;
+    readonly sessions: ScriptedDriverSession[];
+    openError: Error | null;
+    constructor(descriptor: DriverDescriptor);
+    open(spec: DriverOpenSpec, sink: DriverEventSink): Promise<DriverSession>;
+    get last(): ScriptedDriverSession;
+}
+export declare function catalogOf(...factories: DriverFactory[]): DriverCatalog;

package/dist/agent-runtime/session/testing/scripted-driver.js

@@ -0,0 +1,77 @@
+export function descriptor(id, capabilities = {}) {
+    return {
+        id,
+        displayName: id,
+        capabilities: {
+            resident: true,
+            nativeInputQueue: true,
+            subagents: 'supported',
+            subagentDisable: true,
+            subagentModel: true,
+            subagentEffort: true,
+            autonomousContinuation: true,
+            steer: true,
+            toolFiltering: true,
+            usage: { costUsd: 'session-cumulative', tokens: 'per-turn' },
+            ...capabilities,
+        },
+    };
+}
+/** One opened provider process, driven by the test through `emit`. */
+export class ScriptedDriverSession {
+    spec;
+    sink;
+    sent = [];
+    calls = [];
+    closed = null;
+    /** What `stopSubagents` resolves with. */
+    stopResult = 'process';
+    /** Events emitted while closing (e.g. Claude's stopped/killed notifications on SIGTERM). */
+    onClose = [];
+    constructor(spec, sink) {
+        this.spec = spec;
+        this.sink = sink;
+    }
+    emit(...events) {
+        if (this.closed)
+            throw new Error('scripted driver: emit after close');
+        for (const event of events)
+            this.sink(event);
+    }
+    async send(input) { this.calls.push(`send:${input.inputId}`); this.sent.push(input); }
+    async interrupt() { this.calls.push('interrupt'); }
+    async stopSubagents(ids) { this.calls.push(`stopSubagents:${ids?.join(',') ?? '*'}`); return this.stopResult; }
+    async close(reason) {
+        if (this.closed)
+            return;
+        this.calls.push(`close:${reason}`);
+        for (const event of this.onClose)
+            this.sink(event);
+        this.closed = reason;
+    }
+}
+export class ScriptedDriverFactory {
+    descriptor;
+    sessions = [];
+    openError = null;
+    constructor(descriptor) {
+        this.descriptor = descriptor;
+    }
+    async open(spec, sink) {
+        if (this.openError)
+            throw this.openError;
+        const session = new ScriptedDriverSession(spec, sink);
+        this.sessions.push(session);
+        return session;
+    }
+    get last() {
+        const session = this.sessions.at(-1);
+        if (!session)
+            throw new Error('scripted driver: no session opened');
+        return session;
+    }
+}
+export function catalogOf(...factories) {
+    const map = new Map(factories.map((factory) => [factory.descriptor.id, factory]));
+    return { get: (id) => map.get(id), descriptors: () => factories.map((factory) => factory.descriptor) };
+}

package/dist/agent-runtime/verification-proposals.d.ts

@@ -0,0 +1,9 @@
+import type { PipelineContext, VerificationCommand } from '../pipeline/pipeline-state.js';
+/** The package script a command runs (`npm test`, `npm run x`, `pnpm [run] x`, `yarn [run] x`), when it runs exactly one with no extra arguments. */
+export declare function packageScriptOf(command: Pick<VerificationCommand, 'command' | 'args'>): string | undefined;
+/**
+ * The proposals to append to `planned` (already scope-defaulted). `normalize`
+ * applies the caller's scope default; proposals are expected to be
+ * structurally valid.
+ */
+export declare function admitVerificationProposals(context: PipelineContext, planned: readonly VerificationCommand[], proposals: readonly VerificationCommand[], normalize: (command: VerificationCommand) => VerificationCommand): VerificationCommand[];

package/dist/agent-runtime/verification-proposals.js

@@ -0,0 +1,69 @@
+// Which agent-proposed verification commands the host adds to its plan.
+//
+// A repository without configured checks takes the proposals as its checks
+// (validated like any configured command). A repository with configured
+// checks keeps them and may gain only runs of a package script the
+// repository itself declares, such as `npm run test:e2e`: a change whose
+// acceptance needs browser or integration tests then gets host evidence for
+// them, without the agent introducing arbitrary commands next to the
+// configured ones.
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+/** The package script a command runs (`npm test`, `npm run x`, `pnpm [run] x`, `yarn [run] x`), when it runs exactly one with no extra arguments. */
+export function packageScriptOf(command) {
+    const [first, second, ...rest] = command.args;
+    if (command.command === 'npm') {
+        if (first === 'test' && second === undefined)
+            return 'test';
+        if ((first === 'run' || first === 'run-script') && second && !rest.length)
+            return second;
+        return undefined;
+    }
+    if (command.command === 'pnpm' || command.command === 'yarn') {
+        if (first === 'run' && second && !rest.length)
+            return second;
+        if (first && second === undefined && !first.startsWith('-'))
+            return first;
+    }
+    return undefined;
+}
+function declaresScript(directory, script) {
+    const file = path.join(directory, 'package.json');
+    if (!existsSync(file))
+        return false;
+    try {
+        const scripts = JSON.parse(readFileSync(file, 'utf8')).scripts;
+        return !!scripts && typeof scripts[script] === 'string';
+    }
+    catch {
+        return false;
+    }
+}
+const planKey = (command) => JSON.stringify([command.repositoryId, command.cwd ?? '', command.command, command.args]);
+/**
+ * The proposals to append to `planned` (already scope-defaulted). `normalize`
+ * applies the caller's scope default; proposals are expected to be
+ * structurally valid.
+ */
+export function admitVerificationProposals(context, planned, proposals, normalize) {
+    const configured = new Set(planned.map(command => command.repositoryId));
+    const seen = new Set(planned.map(planKey));
+    const admitted = [];
+    for (const raw of proposals) {
+        const repository = context.repositories.find(repo => repo.id === raw.repositoryId);
+        if (!repository)
+            continue;
+        const command = normalize(raw);
+        if (configured.has(raw.repositoryId)) {
+            const script = packageScriptOf(command);
+            if (!script || !declaresScript(path.resolve(repository.path, command.cwd ?? '.'), script))
+                continue;
+        }
+        const key = planKey(command);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        admitted.push(command);
+    }
+    return admitted;
+}

package/dist/installer/util/registry.js

@@ -17,8 +17,8 @@
  * Everything in this module is synchronous to fit the installer's sync flow.
  */
 import { closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
+import { userHome } from '../../shared/specrails-home.js';
 /** Registry schema version. A reader that sees a higher value MUST treat all
  *  entries as absent (legacy fallback), never mis-parse. */
 export const REGISTRY_SCHEMA_VERSION = 1;
@@ -190,9 +190,9 @@ function isValidProjectEntry(key, value, home) {
 export function slugify(name) {
     return name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
 }
-/** `$HOME` for the registry, overridable for tests. */
+/** `$HOME` for the registry, overridable for tests (shared with session journals). */
 function resolveHome(home) {
-    return home ?? process.env.SPECRAILS_REGISTRY_HOME ?? os.homedir();
+    return userHome(home);
 }
 /** Absolute path to `registry.json`. */
 export function registryPath(home) {

package/dist/shared/specrails-home.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The user-level Specrails home. Registry, framework store, workspaces and
+ * agent session journals all live under `<home>/.specrails`, never inside a
+ * project repository.
+ *
+ * `SPECRAILS_REGISTRY_HOME` overrides the base directory so tests (and
+ * isolated installs) redirect every user-level artifact together.
+ */
+export declare function userHome(home?: string): string;
+/** Absolute path to `<home>/.specrails`. */
+export declare function specrailsHome(home?: string): string;
+/** Scope used by session hosts that are not bound to a project. */
+export declare const GLOBAL_SESSION_SCOPE = "global";
+/** True when `scope` is a valid session scope key (a project slug or `global`). */
+export declare function isSessionScopeKey(scope: string): boolean;
+/**
+ * Directory that holds every agent session journal of one scope:
+ * `<home>/.specrails/sessions/<scope>/`. Sessions are grouped per project so a
+ * project's history can be inspected, backed up or removed as one unit.
+ */
+export declare function sessionsRoot(scope: string, home?: string): string;

package/dist/shared/specrails-home.js

@@ -0,0 +1,36 @@
+import os from 'node:os';
+import path from 'node:path';
+/**
+ * The user-level Specrails home. Registry, framework store, workspaces and
+ * agent session journals all live under `<home>/.specrails`, never inside a
+ * project repository.
+ *
+ * `SPECRAILS_REGISTRY_HOME` overrides the base directory so tests (and
+ * isolated installs) redirect every user-level artifact together.
+ */
+export function userHome(home) {
+    return home ?? process.env.SPECRAILS_REGISTRY_HOME ?? os.homedir();
+}
+/** Absolute path to `<home>/.specrails`. */
+export function specrailsHome(home) {
+    return path.join(userHome(home), '.specrails');
+}
+/** Scope used by session hosts that are not bound to a project. */
+export const GLOBAL_SESSION_SCOPE = 'global';
+/** Same alphabet the registry uses for project slugs, bounded for file names. */
+const SCOPE_KEY = /^[a-z0-9](?:[a-z0-9-]{0,126}[a-z0-9])?$/;
+/** True when `scope` is a valid session scope key (a project slug or `global`). */
+export function isSessionScopeKey(scope) {
+    return SCOPE_KEY.test(scope);
+}
+/**
+ * Directory that holds every agent session journal of one scope:
+ * `<home>/.specrails/sessions/<scope>/`. Sessions are grouped per project so a
+ * project's history can be inspected, backed up or removed as one unit.
+ */
+export function sessionsRoot(scope, home) {
+    if (!isSessionScopeKey(scope)) {
+        throw new Error(`Invalid session scope "${scope}": use a project slug (a-z, 0-9, "-") or "${GLOBAL_SESSION_SCOPE}"`);
+    }
+    return path.join(specrailsHome(home), 'sessions', scope);
+}

package/integration-contract.json

@@ -241,7 +241,8 @@
       "workflows",
       "fork",
       "signal",
-      "cancel"
+      "cancel",
+      "host"
     ],
     "cliPresentationOperations": [
       "help"
@@ -373,6 +374,46 @@
     "workflowAgentSteps": {
       "version": 1,
       "ownership": "Host-defined roles, schemas and gates; Core provides scoped artifact contracts and verified candidate guards"
+    },
+    "sessions": {
+      "version": 1,
+      "protocolVersions": [
+        1
+      ],
+      "capability": "sessions",
+      "cliOperation": "host",
+      "cliCommand": "specrails-core runtime host --stdio --scope <projectKey|global>",
+      "transport": "JSON-RPC 2.0 over newline-delimited stdio; one host per scope",
+      "journalRoot": "~/.specrails/sessions/<scope>/sessions.sqlite",
+      "moduleExport": "./agent-runtime/session",
+      "documentation": "docs/agent-sessions/protocol.md",
+      "eventTypes": [
+        "session.opened",
+        "session.phase",
+        "session.process",
+        "session.provider-ref",
+        "session.updated",
+        "session.closed",
+        "input.accepted",
+        "input.state",
+        "turn.started",
+        "turn.output",
+        "turn.tool",
+        "turn.completed",
+        "subagent.started",
+        "subagent.phase",
+        "subagent.output",
+        "subagent.usage",
+        "subagent.result",
+        "subagents.settled",
+        "output.truncated",
+        "notice.interruption",
+        "provider.diagnostic"
+      ],
+      "capabilities": [
+        "sessions",
+        "delegation"
+      ]
     }
   },
   "execution": {