@zergai/ztc 0.5.0-beta.1 → 0.6.0-beta.1

package/dist/runtime_info.js

@@ -5,8 +5,6 @@ import { getVersion } from './utils/version.js';
 const STARTED_AT = new Date();
 const GIT_TIMEOUT_MS = 2_000;
 const DIFF_HASH_TIMEOUT_MS = 5_000;
-/** How long startup waits for a prefetched probe before probing synchronously. */
-const STARTUP_GIT_AWAIT_MS = 750;
 const HASH_LEN = 12;
 function sha(value) {
     return createHash('sha256').update(value).digest('hex').slice(0, HASH_LEN);
@@ -26,7 +24,9 @@ function runGit(cwd, args, timeout = GIT_TIMEOUT_MS) {
             encoding: 'utf8',
             timeout,
             stdio: ['ignore', 'pipe', 'pipe'],
-        }).trim();
+            // Leading spaces carry meaning: porcelain's " M file" is unstaged, and a full trim once turned it into a staged
+            // "M nventory/..." for the model (2026-10-27).
+        }).trimEnd();
         return { ok: true, output };
     }
     catch (error) {
@@ -57,7 +57,7 @@ function getEntrypoint(env) {
  * (what an unavailable repository looks like, which fields survive a failed
  * probe) is decided in exactly one place.
  */
-function assembleStartupGitSnapshot(raw) {
+function assembleGitProbeSnapshot(raw) {
     const { root } = raw;
     if (!root.ok) {
         return {
@@ -174,19 +174,29 @@ function runGitAsync(cwd, args, timeout = GIT_TIMEOUT_MS) {
                 resolve({ ok: false, failure });
                 return;
             }
-            resolve({ ok: true, output: String(stdout).trim() });
+            resolve({ ok: true, output: String(stdout).trimEnd() }); // Leading spaces carry meaning (see runGit).
         });
     });
 }
+/**
+ * The asynchronous gatherer launches its probes together rather than chaining
+ * them: each step of a chain waits for the main thread to handle the previous
+ * exit, and during startup the main thread is busy compiling modules for most
+ * of a second, so a chain stalls between commands. The probes are independent
+ * reads; outside a repository they all fail fast and the results are read the
+ * same way the synchronous chain reads them.
+ */
 async function gatherGitOutputsAsync(cwd, includeDirtyHash) {
-    const root = await runGitAsync(cwd, ['rev-parse', '--show-toplevel']);
+    const [root, head, branch, status] = await Promise.all([
+        runGitAsync(cwd, ['rev-parse', '--show-toplevel']),
+        runGitAsync(cwd, ['rev-parse', 'HEAD']),
+        runGitAsync(cwd, ['branch', '--show-current']),
+        runGitAsync(cwd, ['status', '--porcelain=v1']),
+    ]);
     if (!root.ok)
         return { root, head: null, branch: null, status: null, staged: null, unstaged: null };
-    const head = await runGitAsync(cwd, ['rev-parse', 'HEAD']);
     if (!head.ok)
         return { root, head, branch: null, status: null, staged: null, unstaged: null };
-    const branch = await runGitAsync(cwd, ['branch', '--show-current']);
-    const status = await runGitAsync(cwd, ['status', '--porcelain=v1']);
     if (!statusHasChanges(status) || !includeDirtyHash) {
         return { root, head, branch, status, staged: null, unstaged: null };
     }
@@ -200,7 +210,37 @@ async function gatherGitOutputsAsync(cwd, includeDirtyHash) {
     };
 }
 function probeGit(cwd, includeDirtyHash) {
-    return assembleStartupGitSnapshot(gatherGitOutputsSync(cwd, includeDirtyHash));
+    return assembleGitProbeSnapshot(gatherGitOutputsSync(cwd, includeDirtyHash));
+}
+/** origin's default branch, else `main` if it exists, else `master` if it exists, else `main`. */
+function mainBranchName(symbolic, mainExists, masterExists) {
+    if (symbolic.ok && symbolic.output)
+        return symbolic.output.replace('refs/remotes/origin/', '');
+    return !mainExists && masterExists ? 'master' : 'main';
+}
+function gatherPromptContextSync(cwd) {
+    const symbolic = runGit(cwd, ['symbolic-ref', 'refs/remotes/origin/HEAD']);
+    const mainExists = !symbolic.ok && runGit(cwd, ['rev-parse', '--verify', 'main']).ok;
+    const masterExists = !symbolic.ok && !mainExists && runGit(cwd, ['rev-parse', '--verify', 'master']).ok;
+    const log = runGit(cwd, ['log', '--oneline', '-5']);
+    return { mainBranch: mainBranchName(symbolic, mainExists, masterExists), recentCommits: log.ok ? log.output : '' };
+}
+async function gatherPromptContextAsync(cwd) {
+    const [symbolic, main, master, log] = await Promise.all([
+        runGitAsync(cwd, ['symbolic-ref', 'refs/remotes/origin/HEAD']),
+        runGitAsync(cwd, ['rev-parse', '--verify', 'main']),
+        runGitAsync(cwd, ['rev-parse', '--verify', 'master']),
+        runGitAsync(cwd, ['log', '--oneline', '-5']),
+    ]);
+    return { mainBranch: mainBranchName(symbolic, main.ok, master.ok), recentCommits: log.ok ? log.output : '' };
+}
+function withPromptContext(probe, context) {
+    const inRepository = probe.git.available === true;
+    return {
+        ...probe,
+        mainBranch: inRepository ? context.mainBranch : null,
+        recentCommits: inRepository ? context.recentCommits : '',
+    };
 }
 function getGitInfo(cwd, includeDirtyHash = true) {
     return probeGit(cwd, includeDirtyHash).git;
@@ -233,7 +273,9 @@ let startupGitPrefetch = null;
  */
 function captureStartupGitSnapshot(cwd) {
     if (startupGitSnapshot === null || startupGitSnapshot.cwd !== cwd) {
-        startupGitSnapshot = { cwd, value: probeGit(cwd, false) };
+        const probe = probeGit(cwd, false);
+        const context = probe.git.available === true ? gatherPromptContextSync(cwd) : { mainBranch: 'main', recentCommits: '' };
+        startupGitSnapshot = { cwd, value: withPromptContext(probe, context) };
     }
     return startupGitSnapshot.value;
 }
@@ -257,8 +299,9 @@ export function prefetchStartupGitSnapshot(cwd) {
         return;
     if (startupGitPrefetch !== null && startupGitPrefetch.cwd === cwd)
         return;
-    const promise = gatherGitOutputsAsync(cwd, false).then((raw) => {
-        const value = assembleStartupGitSnapshot(raw);
+    // The prompt-only probes run alongside the status scan, so they add no wall time.
+    const promise = Promise.all([gatherGitOutputsAsync(cwd, false), gatherPromptContextAsync(cwd)]).then(([raw, context]) => {
+        const value = withPromptContext(assembleGitProbeSnapshot(raw), context);
         if (startupGitSnapshot === null || startupGitSnapshot.cwd !== cwd) {
             startupGitSnapshot = { cwd, value };
         }
@@ -270,28 +313,21 @@ export function prefetchStartupGitSnapshot(cwd) {
     startupGitPrefetch = { cwd, promise };
 }
 /**
- * Wait briefly for an in-flight prefetch, then read the snapshot.
+ * Wait for an in-flight prefetch, then read the snapshot.
  *
  * Startup waits here before the first consumer runs, so that consumer reads a
- * resolved value rather than falling back to the synchronous probe. The wait is
- * bounded: if the scan has not finished (a pathological repository, or no
- * prefetch was ever started) the read falls through to the synchronous probe
- * and startup still gets an answer.
+ * resolved value rather than probing synchronously. The wait is not cut short:
+ * a synchronous fallback would rerun the same scan from the start and block the
+ * event loop while doing it, so it could only finish later. Each git command in
+ * the prefetch has its own timeout, so the wait always ends. Without a prefetch
+ * for `cwd` the read probes synchronously.
  */
 export async function awaitStartupGitSnapshot(cwd) {
     const pending = startupGitPrefetch;
-    if (pending !== null && pending.cwd === cwd) {
-        await Promise.race([pending.promise, waitForStartupGitSnapshotBound()]);
-    }
+    if (pending !== null && pending.cwd === cwd)
+        await pending.promise;
     return captureStartupGitSnapshot(cwd);
 }
-/** Resolves after the bound; never the only thing holding the process open. */
-function waitForStartupGitSnapshotBound() {
-    return new Promise((resolve) => {
-        const timer = setTimeout(resolve, STARTUP_GIT_AWAIT_MS);
-        timer.unref();
-    });
-}
 /** Test seam: drop the memoised startup snapshot and any pending prefetch. */
 export function __resetStartupGitSnapshotForTest() {
     startupGitPrefetch = null;

package/dist/session.d.ts

@@ -69,6 +69,7 @@ export interface SessionRuntimeState {
         name: string;
     } | null;
     taskHandoffInput?: TaskHandoffInput;
+    hostScaffold?: HostScaffoldRow[];
     evidence?: EvidenceSnapshot;
     diagnostics?: DiagnosticSnapshot;
     usage?: UsageSnapshot;
@@ -88,12 +89,18 @@ export interface SessionRuntimeState {
  * understand.
  */
 export declare const SESSION_SCHEMA_VERSION = 1;
+export interface HostScaffoldRow {
+    id: string;
+    content: string;
+    capturedAt: string;
+}
 /** Shared guard for latency-sensitive session reads such as launch and navigator previews. */
 export declare const MAX_SESSION_FILE_BYTES: number;
 export interface Session {
     /** One explicit terminal task/card association, not a second task store. */
     board_binding?: BoardSessionBinding;
     task_handoff?: TaskHandoffSnapshot;
+    host_scaffold?: HostScaffoldRow[];
     evidence?: EvidenceSnapshot;
     diagnostics?: DiagnosticSnapshot;
     usage?: UsageSnapshot;
@@ -135,6 +142,8 @@ export declare const COLONY_WORKTREE_MARKER = ".colony-worktree.json";
  * when the key is absent or its object does not close inside `text`.
  */
 export declare function extractTopLevelJsonObject(text: string, key: string): string | null;
+/** Where sessions live: ZTC_SESSIONS_DIR, or ~/.ztc/sessions. */
+export declare function getGlobalSessionsRoot(): string;
 export declare function getProjectHash(cwd: string): string;
 export declare function generateSessionId(): string;
 export declare function hasSessionSelector(args: string[]): boolean;

package/dist/session.js

@@ -18,7 +18,7 @@ import { basename, dirname, join, relative, resolve, sep } from 'path';
 import { homedir } from 'os';
 import { createHash } from 'crypto';
 import { parseEvidenceSnapshot } from './agent/runtime/evidence.js';
-import { mergeDiagnosticSnapshots, parseDiagnosticSnapshot } from './diagnostics/session_export.js';
+import { admitStoredDiagnosticSnapshot, mergeDiagnosticSnapshots } from './diagnostics/session_export.js';
 import { mergeUsageSnapshots, parseUsageSnapshot } from './usage_snapshot.js';
 import { writeFileAtomic } from './utils/atomic_write.js';
 import { withPathLock } from './utils/path_lock.js';
@@ -118,7 +118,7 @@ function isSessionShape(value) {
     return true;
 }
 function admitSessionDiagnostics(value, path) {
-    const snapshot = parseDiagnosticSnapshot(value);
+    const snapshot = admitStoredDiagnosticSnapshot(value);
     if (snapshot === null) {
         throw new SessionLoadError(`Session file ${path} contains invalid or unsupported diagnostics`, 'diagnostics-invalid', path);
     }
@@ -134,8 +134,8 @@ function mergeSessionDiagnostics(runtimeState, existing, path) {
     try {
         return mergeDiagnosticSnapshots(prior, current);
     }
-    catch (error) {
-        throw new SessionLoadError(`Session file ${path} contains conflicting diagnostic identities`, 'diagnostics-invalid', path, error);
+    catch {
+        return admitStoredDiagnosticSnapshot(current) ?? prior;
     }
 }
 function normalizeLoadedSession(session, path) {
@@ -431,7 +431,8 @@ async function readSessionHeadSummary(entry) {
 function getHomeDir() {
     return process.env.HOME || process.env.USERPROFILE || homedir();
 }
-function getGlobalSessionsRoot() {
+/** Where sessions live: ZTC_SESSIONS_DIR, or ~/.ztc/sessions. */
+export function getGlobalSessionsRoot() {
     return process.env.ZTC_SESSIONS_DIR || join(getHomeDir(), '.ztc', 'sessions');
 }
 function getGlobalColonyRoot() {
@@ -440,10 +441,16 @@ function getGlobalColonyRoot() {
 export function getProjectHash(cwd) {
     return createHash('sha256').update(cwd).digest('hex').slice(0, 12);
 }
+/** Ids minted by this process: they cannot exist anywhere it has not saved them. */
+const sessionIdsGeneratedHere = new Set();
+/** Where this process last saved each session, for saves after a cwd change. */
+const sessionStorageSavedHere = new Map();
 export function generateSessionId() {
     const timestamp = Date.now().toString(36);
     const random = Math.random().toString(36).slice(2, 8);
-    return `${timestamp}-${random}`;
+    const sessionId = `${timestamp}-${random}`;
+    sessionIdsGeneratedHere.add(sessionId);
+    return sessionId;
 }
 export function hasSessionSelector(args) {
     for (let i = 0; i < args.length; i++) {
@@ -1032,7 +1039,14 @@ export async function bindToolResponseStoreToSession(store, discovered, cwd, ses
     const restoreExportedEvidence = async (path) => {
         const session = await loadSessionFromFile(path, false);
         const exported = session?.evidence;
-        if (!exported || exported.revision <= store.evidence.getSnapshot().revision)
+        if (!exported)
+            return;
+        const current = store.evidence.getSnapshot();
+        // A fresh store's setSessionDir clears its empty ledger to revision 1.
+        // That reset counter is not retained evidence and must not hide the first
+        // portable record. Existing equal/newer disk facts remain authoritative.
+        if (exported.revision < current.revision
+            || (exported.revision === current.revision && current.records.length > 0))
             return;
         store.evidence.restore(exported);
         for (const record of exported.records) {
@@ -1065,7 +1079,7 @@ export async function saveSession(sessionId, cwd, messages, model, provider, mux
     await retainSessionForProcess(getSessionCoordinationDirectory(storage), sessionId);
     await ensureSessionStorage(storage, sessionId);
     const sessionPath = getSessionJsonPath(storage, sessionId);
-    const existingSession = await loadSessionById(sessionId, cwd);
+    const existingSession = await findSessionToMerge(sessionId, cwd);
     const title = deriveSessionTitle(messages, existingSession?.metadata.title);
     // User-set names remain independently controlled by /rename.
     const session = {
@@ -1088,12 +1102,14 @@ export async function saveSession(sessionId, cwd, messages, model, provider, mux
         diagnostics: mergeSessionDiagnostics(runtimeState, existingSession, sessionPath),
         usage: mergeSessionUsage(runtimeState, existingSession, sessionPath),
         task_handoff: undefined,
+        host_scaffold: runtimeState?.hostScaffold ?? existingSession?.host_scaffold,
         messages: stripEphemeralMessages(messages),
         mux_state: muxState,
         pane_specs: paneSpecs,
         hosted_settings: hostedSettings ?? existingSession?.hosted_settings,
     };
     await writeSessionWithMedia(sessionPath, session, runtimeState, existingSession, signal);
+    sessionStorageSavedHere.set(sessionId, storage);
     const muxStatePath = getMuxStateFilePath(storage, sessionId);
     if (muxStatePath) {
         if (muxState) {
@@ -1105,6 +1121,22 @@ export async function saveSession(sessionId, cwd, messages, model, provider, mux
     }
     return sessionPath;
 }
+/**
+ * The existing copy saveSession merges metadata from. An id minted by this
+ * process can only be where this process saved it, so it skips the search
+ * across every project folder; any other id keeps the full lookup.
+ */
+async function findSessionToMerge(sessionId, cwd) {
+    if (!sessionIdsGeneratedHere.has(sessionId))
+        return loadSessionById(sessionId, cwd);
+    for (const storage of getStorageCandidates(cwd)) {
+        const session = await loadSessionFromStorage(storage, sessionId);
+        if (session)
+            return session;
+    }
+    const savedStorage = sessionStorageSavedHere.get(sessionId);
+    return savedStorage ? loadSessionFromStorage(savedStorage, sessionId) : null;
+}
 /**
  * Load a global session from disk. Handles legacy flat-file migration.
  */
@@ -1225,6 +1257,7 @@ export async function saveSessionToFile(path, sessionId, cwd, messages, model, p
         diagnostics: mergeSessionDiagnostics(runtimeState, existingSession, path),
         usage: mergeSessionUsage(runtimeState, existingSession, path),
         task_handoff: undefined,
+        host_scaffold: runtimeState?.hostScaffold ?? existingSession?.host_scaffold,
         messages: stripEphemeralMessages(messages),
         mux_state: muxState,
         pane_specs: paneSpecs,

package/dist/session_handoff_contract.d.ts

@@ -85,5 +85,18 @@ export interface TaskHandoffProjection {
 export declare function parseTaskHandoffSnapshot(value: unknown): TaskHandoffSnapshot | null;
 export declare function parseTaskHandoffProjection(value: unknown): TaskHandoffProjection | null;
 export declare function projectTaskHandoff(snapshot: TaskHandoffSnapshot): TaskHandoffProjection;
+/**
+ * What a person sees of a saved checkpoint: what it was, how to resume it, and
+ * what it must not be taken to prove. Ownership, objective source, recorded
+ * observations, blockers and omission counts stay in the model's context
+ * (formatTaskHandoffContext) only.
+ */
+export declare function formatTaskHandoffSummary(snapshot: TaskHandoffSnapshot): string;
 /** Historical checkpoint context; display alone never resumes or repeats an operation. */
 export declare function formatTaskHandoffContext(snapshot: TaskHandoffSnapshot): string;
+/**
+ * What a resumed launch shows of a saved checkpoint: what it was, that nothing
+ * replays, and anything left uncertain. The full record (identities, revision,
+ * the no-replay contract) is /handoff's; the model keeps all of it as context.
+ */
+export declare function formatTaskHandoffNotice(snapshot: TaskHandoffSnapshot): string;

package/dist/session_handoff_contract.js

@@ -140,40 +140,106 @@ export function projectTaskHandoff(snapshot) {
         throw new TypeError('Invalid task handoff checkpoint');
     return { snapshot: parsed, resumeCommand: resumeSelector(parsed.source.sessionId), provenance: 'validated_session_checkpoint', ownerLiveness: 'unknown', asOf: parsed.source.capturedAt };
 }
+/** Shared rendering: control bytes removed, saved authored data unchanged. */
+function handoffDisplay(value) {
+    return value.replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/gu, char => char === '\n' ? ' ↵ ' : ' ');
+}
+/** The checkpoint's identity rows, shown to both the person and the model. */
+function handoffHeadRows(projection) {
+    const value = projection.snapshot;
+    return [
+        '[Saved task handoff — source-qualified checkpoint]',
+        // Only a goal is the objective: a resumed session's first request read as one, and the model redid that
+        // finished task instead of the latest request (2026-10-27).
+        value.objective.kind === 'goal' ? `Objective: ${handoffDisplay(value.objective.text)}` : `First request: ${handoffDisplay(value.objective.text)}`,
+        `Task: ${handoffDisplay(value.taskId)}; recorded status: ${value.taskStatus}${value.objective.kind === 'opening_request' ? ' (the session\'s first request; later requests may have finished or replaced it)' : ''}.`,
+        `Source session: ${handoffDisplay(value.source.sessionId)}; checkpoint as-of ${projection.asOf}; revision ${value.revision}.`,
+        `Resume: ${handoffDisplay(projection.resumeCommand)} (source directory: ${handoffDisplay(value.source.cwd)}).`,
+    ];
+}
+const HANDOFF_NO_REPLAY = 'This checkpoint does not authorize new actions or prove semantic completion. Inspect unresolved outcomes and uncertain delivery; never automatically replay them.';
+function handoffUnresolvedRows(value) {
+    return value.unresolvedCalls.map(row => `Unresolved call: ${handoffDisplay(row.toolCallId)} (${handoffDisplay(row.name)}); outcome unknown; source message ${handoffDisplay(row.sourceMessageId)}.`);
+}
+function handoffCorrectionRows(value) {
+    return value.corrections.map(row => {
+        const authoredText = row.deliveryState === 'pending' ? 'deferred authored text withheld until delivery' : handoffDisplay(row.text);
+        return `Recorded correction ${handoffDisplay(row.id)}: ${row.delivery}, recorded delivery ${row.deliveryState}; current dispatch state unknown; current task applicability unconfirmed; ${authoredText}${row.sourceMessageId ? ` (source ${handoffDisplay(row.sourceMessageId)})` : ' (source reference unavailable)'}.`;
+    });
+}
+function handoffNextActionRow(value) {
+    return value.nextAction.availability === 'unavailable' ? 'Next action: unavailable in this source checkpoint.' : `Recorded next action (unverified; source ${handoffDisplay(value.nextAction.sourceMessageId ?? '')}): ${handoffDisplay(value.nextAction.text ?? '')}`;
+}
+/**
+ * What a person sees of a saved checkpoint: what it was, how to resume it, and
+ * what it must not be taken to prove. Ownership, objective source, recorded
+ * observations, blockers and omission counts stay in the model's context
+ * (formatTaskHandoffContext) only.
+ */
+export function formatTaskHandoffSummary(snapshot) {
+    const projection = projectTaskHandoff(snapshot);
+    const value = projection.snapshot;
+    return [
+        ...handoffHeadRows(projection),
+        HANDOFF_NO_REPLAY,
+        ...handoffUnresolvedRows(value),
+        ...handoffCorrectionRows(value),
+        handoffNextActionRow(value),
+    ].join('\n');
+}
 /** Historical checkpoint context; display alone never resumes or repeats an operation. */
 export function formatTaskHandoffContext(snapshot) {
     const projection = projectTaskHandoff(snapshot);
-    // Rendering removes terminal control bytes without changing saved authored data.
-    const display = (value) => value.replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/gu, char => char === '\n' ? ' ↵ ' : ' ');
+    const display = handoffDisplay;
     const value = projection.snapshot;
     const lines = [
-        '[Saved task handoff — source-qualified checkpoint]',
-        `Objective: ${display(value.objective.text)}`,
-        `Task: ${display(value.taskId)}; recorded status: ${value.taskStatus}${value.objective.kind === 'opening_request' ? ' (opening request; current task lifecycle unknown)' : ''}.`,
-        `Source session: ${display(value.source.sessionId)}; checkpoint as-of ${projection.asOf}; revision ${value.revision}.`,
-        `Resume: ${display(projection.resumeCommand)} (source directory: ${display(value.source.cwd)}).`,
+        ...handoffHeadRows(projection),
         `Historical owner: PID ${value.owner.pid ?? 'unknown'}, pane ${value.owner.paneId ?? 'unknown'}; current owner liveness unknown. Recorded identity does not establish current ownership.`,
         value.objective.sourceAvailability === 'historical_checkpoint'
             ? `Objective source: historical checkpoint only; original message ${display(value.objective.sourceMessageId ?? '')} is unavailable.`
             : `Objective source: ${display(value.objective.goalId ?? value.objective.sourceMessageId ?? '')}; source identity present in this checkpoint.`,
-        'This checkpoint does not authorize new actions or prove semantic completion. Inspect unresolved outcomes and uncertain delivery; never automatically replay them.',
+        HANDOFF_NO_REPLAY,
     ];
     for (const row of value.completedObservations)
         lines.push(`Recorded terminal process: ${display(row.observationId)}; call ${display(row.toolCallId)}; job ${display(row.jobId)}; ${row.status}, exit ${row.exitCode ?? 'unknown'}; semantic verification unknown; current task applicability unconfirmed.`);
     if (!value.completedObservations.length)
         lines.push('Recorded terminal observations: unavailable.');
-    for (const row of value.unresolvedCalls)
-        lines.push(`Unresolved call: ${display(row.toolCallId)} (${display(row.name)}); outcome unknown; source message ${display(row.sourceMessageId)}.`);
-    for (const row of value.corrections) {
-        const authoredText = row.deliveryState === 'pending' ? 'deferred authored text withheld until delivery' : display(row.text);
-        lines.push(`Recorded correction ${display(row.id)}: ${row.delivery}, recorded delivery ${row.deliveryState}; current dispatch state unknown; current task applicability unconfirmed; ${authoredText}${row.sourceMessageId ? ` (source ${display(row.sourceMessageId)})` : ' (source reference unavailable)'}.`);
-    }
+    lines.push(...handoffUnresolvedRows(value), ...handoffCorrectionRows(value));
     for (const row of value.blockers)
         lines.push(`Recorded blocker (goal ${display(row.sourceGoalId)}; unverified): ${display(row.text)}`);
     if (!value.blockers.length)
         lines.push('Blockers: unavailable in this source checkpoint.');
-    lines.push(value.nextAction.availability === 'unavailable' ? 'Next action: unavailable in this source checkpoint.' : `Recorded next action (unverified; source ${display(value.nextAction.sourceMessageId ?? '')}): ${display(value.nextAction.text ?? '')}`);
+    lines.push(handoffNextActionRow(value));
     const omitted = value.omitted;
     lines.push(`Omitted from summary: ${omitted.corrections} corrections, ${omitted.completedObservations} process observations, ${omitted.unresolvedCalls} unresolved calls, ${omitted.textBytes} text bytes. Recall original source messages and result handles for omitted data.`);
     return lines.join('\n');
 }
+const NOTICE_OBJECTIVE_CHARS = 60;
+function plural(count, one, many = `${one}s`) {
+    return `${count} ${count === 1 ? one : many}`;
+}
+/**
+ * What a resumed launch shows of a saved checkpoint: what it was, that nothing
+ * replays, and anything left uncertain. The full record (identities, revision,
+ * the no-replay contract) is /handoff's; the model keeps all of it as context.
+ */
+export function formatTaskHandoffNotice(snapshot) {
+    const value = projectTaskHandoff(snapshot).snapshot;
+    // One line: newlines and control bytes read as spaces here, not as ↵.
+    const text = value.objective.text.replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/gu, ' ').replace(/\s+/g, ' ').trim();
+    const objective = [...text].length > NOTICE_OBJECTIVE_CHARS
+        ? `${[...text].slice(0, NOTICE_OBJECTIVE_CHARS - 1).join('').trimEnd()}…` : text;
+    const kind = value.objective.kind === 'goal' ? 'goal' : 'task';
+    const cautions = [];
+    if (value.unresolvedCalls.length) {
+        cautions.push(`${plural(value.unresolvedCalls.length, 'tool call')} ended with an unknown outcome`);
+    }
+    const undelivered = value.corrections.filter(row => row.deliveryState !== 'delivered').length;
+    if (undelivered) {
+        cautions.push(`${plural(undelivered, 'queued correction')} ${undelivered === 1 ? 'was' : 'were'} not confirmed delivered`);
+    }
+    const follow = cautions.length
+        ? `${cautions.join('; ')}. Check before continuing; nothing is replayed. /handoff shows the checkpoint.`
+        : 'Nothing is replayed. /handoff shows the checkpoint.';
+    return [`Saved ${kind}: "${objective}" · status ${value.taskStatus.replace(/_/g, ' ')}`, follow].join('\n');
+}

package/dist/session_media.d.ts

@@ -24,6 +24,11 @@ export interface PreparedSessionMedia {
     /** Idempotent; after commitment this deliberately retains every owned image. */
     rollback(): Promise<void>;
 }
+/** Media type of PNG, JPEG, GIF or WebP bytes, by signature; null for anything else. */
+export declare function imageType(data: Buffer): {
+    mediaType: string;
+    extension: string;
+} | null;
 /**
  * A durable ref is authority only when its actual checkpoint contains that exact
  * attachment. Paths are derived from the owner sidecar; localPath is never trusted.

package/dist/session_media.js

@@ -31,7 +31,8 @@ function canonicalCheckpoint(path) {
     }
     return join(realpathSync(dirname(path)), basename(path));
 }
-function imageType(data) {
+/** Media type of PNG, JPEG, GIF or WebP bytes, by signature; null for anything else. */
+export function imageType(data) {
     if (data.length >= 8 && data.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) {
         return { mediaType: 'image/png', extension: 'png' };
     }

package/dist/simulation/domain_types.d.ts

@@ -11,6 +11,7 @@
  */
 import type { SyntheticIdentity, SimAgent, WorldModel, GroundedVariables, MutationSchema, WorldMutationRequest, Deadline, ConceptNode } from './types.js';
 import type { RelationshipGraph } from './world/topology.js';
+import type { ToolParameterSchema } from '../types.js';
 import type { CoordinatorTuning } from './orchestration/coordinator_tuning.js';
 import type { CausalGraph } from './world/causal_graph.js';
 export interface PacingConfig {
@@ -41,9 +42,8 @@ export interface DomainToolDef {
     name: string;
     handler: string;
     description: string;
-    parameters: Record<string, {
-        type: string;
-        description: string;
+    parameters: Record<string, Omit<ToolParameterSchema, 'required'> & {
+        required?: boolean | string[];
     }>;
     required?: string[];
     document_type?: string;

package/dist/simulation/living/context.d.ts

@@ -226,7 +226,7 @@ export declare function gameMasterAttemptInput(state: LivingState, actorId: stri
         meaning: string;
         properties: {
             id: string;
-            type: "number" | "id" | "flag" | "text" | "level" | "time";
+            type: "number" | "text" | "id" | "flag" | "level" | "time";
             requiredOnCreate?: boolean | undefined;
         }[];
         relations: {
@@ -463,7 +463,7 @@ export declare function gameMasterAttemptInput(state: LivingState, actorId: stri
         meaning: string;
         properties: {
             id: string;
-            type: "number" | "id" | "flag" | "text" | "level" | "time";
+            type: "number" | "text" | "id" | "flag" | "level" | "time";
             requiredOnCreate?: boolean | undefined;
         }[];
         relations: {
@@ -705,7 +705,7 @@ export declare function gameMasterAttemptInput(state: LivingState, actorId: stri
         meaning: string;
         properties: {
             id: string;
-            type: "number" | "id" | "flag" | "text" | "level" | "time";
+            type: "number" | "text" | "id" | "flag" | "level" | "time";
             requiredOnCreate?: boolean | undefined;
         }[];
         relations: {
@@ -949,7 +949,7 @@ export declare function gameMasterAttemptInput(state: LivingState, actorId: stri
         meaning: string;
         properties: {
             id: string;
-            type: "number" | "id" | "flag" | "text" | "level" | "time";
+            type: "number" | "text" | "id" | "flag" | "level" | "time";
             requiredOnCreate?: boolean | undefined;
         }[];
         relations: {
@@ -1205,7 +1205,7 @@ export declare function gameMasterWorldInput(state: LivingState, happening: {
         meaning: string;
         properties: {
             id: string;
-            type: "number" | "id" | "flag" | "text" | "level" | "time";
+            type: "number" | "text" | "id" | "flag" | "level" | "time";
             requiredOnCreate?: boolean | undefined;
         }[];
         relations: {
@@ -1425,7 +1425,7 @@ export declare function gameMasterWorldInput(state: LivingState, happening: {
         meaning: string;
         properties: {
             id: string;
-            type: "number" | "id" | "flag" | "text" | "level" | "time";
+            type: "number" | "text" | "id" | "flag" | "level" | "time";
             requiredOnCreate?: boolean | undefined;
         }[];
         relations: {
@@ -1650,7 +1650,7 @@ export declare function gameMasterWorldInput(state: LivingState, happening: {
         meaning: string;
         properties: {
             id: string;
-            type: "number" | "id" | "flag" | "text" | "level" | "time";
+            type: "number" | "text" | "id" | "flag" | "level" | "time";
             requiredOnCreate?: boolean | undefined;
         }[];
         relations: {
@@ -1877,7 +1877,7 @@ export declare function gameMasterWorldInput(state: LivingState, happening: {
         meaning: string;
         properties: {
             id: string;
-            type: "number" | "id" | "flag" | "text" | "level" | "time";
+            type: "number" | "text" | "id" | "flag" | "level" | "time";
             requiredOnCreate?: boolean | undefined;
         }[];
         relations: {
@@ -3091,7 +3091,7 @@ export declare function epilogueInput(state: LivingState): {
     votes: {
         name: string;
         question: string;
-        result: "failed" | "passed" | "lapsed" | null;
+        result: "passed" | "failed" | "lapsed" | null;
         count: string | null;
         ballots: {
             name: string;

package/dist/simulation/living/definition.d.ts

@@ -103,9 +103,9 @@ export declare const definitionSchema: z.ZodObject<{
             id: z.ZodString;
             type: z.ZodEnum<{
                 number: "number";
+                text: "text";
                 id: "id";
                 flag: "flag";
-                text: "text";
                 level: "level";
                 time: "time";
             }>;

package/dist/simulation/living/open-world.d.ts

@@ -16,9 +16,9 @@ export declare const propertyDefinitionSchema: z.ZodObject<{
     id: z.ZodString;
     type: z.ZodEnum<{
         number: "number";
+        text: "text";
         id: "id";
         flag: "flag";
-        text: "text";
         level: "level";
         time: "time";
     }>;
@@ -92,9 +92,9 @@ export declare const kindDefinitionSchema: z.ZodObject<{
         id: z.ZodString;
         type: z.ZodEnum<{
             number: "number";
+            text: "text";
             id: "id";
             flag: "flag";
-            text: "text";
             level: "level";
             time: "time";
         }>;
@@ -206,8 +206,8 @@ export declare const entitySchema: z.ZodObject<{
         abstain: "abstain";
     }>>>;
     result: z.ZodOptional<z.ZodEnum<{
-        failed: "failed";
         passed: "passed";
+        failed: "failed";
         lapsed: "lapsed";
     }>>;
     settles: z.ZodOptional<z.ZodString>;

package/dist/simulation/living/recall.d.ts

@@ -9,7 +9,7 @@ export declare function recallBeliefs(person: LivingPerson, cues: readonly strin
     subject: string;
     claim: string;
     source: {
-        kind: "initial" | "inferred" | "witnessed" | "told" | "discovered";
+        kind: "inferred" | "initial" | "witnessed" | "told" | "discovered";
         personId: string | null;
         eventSeq: number;
     };