@akagilnc/pi-workflow-roles 0.1.4035 → 0.1.4193

package/src/submission-ledger.ts

@@ -1,13 +1,23 @@
+import { join } from "node:path";
+
 import {
   resolveActivationLedgerHome,
   tryHomeFromAkRolesPath,
 } from "./activation-ledger-topology.ts";
-import type { HostContext, HostToolResult, RoleHost } from "./host-contracts.ts";
+import {
+  courtAttemptIdFromHostContext,
+  runDirectoryFromHostContext,
+  type HostContext,
+  type HostToolResult,
+  type RoleHost,
+} from "./host-contracts.ts";
 import { isAuditEscalationProjection } from "./audit-escalation.ts";
 
 
 import { runIdFromRunDirectory } from "./run-terminal-artifacts.ts";
 import { readSitianRecords, resolveSitianRecordPathInLedger, sitianReport, type RecordPointer } from "./sitian-facade.ts";
+import type { SitianRecord } from "./sitian-contracts.ts";
+import { findRunDirectoryById } from "./public-cli/run-lifecycle.ts";
 import type { TerminalRoleName } from "./public-cli/terminal.ts";
 import { isCorrectableExecuteError } from "./submission-correctable-error.ts";
 import { failOnInfrastructureFailureDeclaration } from "./package-contracts/terminating-infrastructure.ts";
@@ -57,8 +67,8 @@ export type SubmissionLedgerEvent =
  * otherwise session header id. Never a shared "unbound" bucket.
  */
 function runIdentity(context: HostContext): string {
-  const directory = process.env.AK_ROLE_RUN_DIR;
-  if (typeof directory === "string" && directory.length > 0) {
+  const directory = runDirectoryFromHostContext(context);
+  if (directory !== undefined) {
     const fromDir = runIdFromRunDirectory(directory);
     if (fromDir !== undefined) return fromDir;
   }
@@ -74,8 +84,8 @@ function runIdentity(context: HostContext): string {
 export const COURT_ATTEMPT_ENV = "AK_ROLE_COURT_ATTEMPT" as const;
 
 function attemptIdentity(context: HostContext, runId: string): string {
-  const courtAttempt = process.env[COURT_ATTEMPT_ENV];
-  if (typeof courtAttempt === "string" && courtAttempt.length > 0) return courtAttempt;
+  const courtAttempt = courtAttemptIdFromHostContext(context);
+  if (courtAttempt !== undefined) return courtAttempt;
   return context.sessionManager.getHeader?.()?.id ?? context.sessionManager.getLeafId?.() ?? `${runId}:initial`;
 }
 
@@ -105,28 +115,64 @@ export type ClosedSubmission = {
 
 export type ClosedSubmissionProjection = ClosedSubmission;
 
-function submissionRecordFile(cwd: string, runId: string, home?: string): string {
-  const ledgerHome = resolveActivationLedgerHome(home);
+/**
+ * Resolve the submission-ledger record file for a run.
+ * Unknown run (no sessionParent and no discoverable directory) → undefined so
+ * read APIs return their empty set at the read boundary. Write paths always
+ * supply sessionParent and keep the ownership gate.
+ */
+async function submissionRecordFile(cwd: string, runId: string, scope: SubmissionLedgerReadScope): Promise<string | undefined> {
+  const ledgerHome = resolveActivationLedgerHome(scope.home);
+  let sessionParent = scope.sessionParent;
+  if (sessionParent === undefined) {
+    const discoveredRun = await findRunDirectoryById(scope.home, runId);
+    if (discoveredRun === undefined) return undefined;
+    sessionParent = join(discoveredRun, "session", "session.jsonl");
+  }
   return resolveSitianRecordPathInLedger({
     level: "event",
     kind: "candidate",
     subject: { runId },
     cwd,
+    sessionParent,
   }, ledgerHome).recordFile;
 }
 
-async function readOwnedSubmissionRecords(cwd: string, runId: string, home?: string) {
-  const file = submissionRecordFile(cwd, runId, home);
+/**
+ * Discriminated owned-row view:
+ * - unknown run → file absent + empty owned (read APIs only)
+ * - located ledger → file is string; prior/write consumers may build RecordPointer
+ */
+type OwnedSubmissionRecords =
+  | { readonly file: undefined; readonly owned: readonly [] }
+  | { readonly file: string; readonly owned: readonly SitianRecord[] };
+
+async function readOwnedSubmissionRecords(
+  cwd: string,
+  runId: string,
+  scope: SubmissionLedgerReadScope = {},
+): Promise<OwnedSubmissionRecords> {
+  const file = await submissionRecordFile(cwd, runId, scope);
+  if (file === undefined) {
+    return { file: undefined, owned: [] };
+  }
   const { records } = await readSitianRecords(file);
   return {
     file,
-    owned: records.filter((record) => typeof record.subject === "object" && record.subject !== null && (record.subject as { runId?: string }).runId === runId),
+    owned: records.filter(
+      (record) =>
+        typeof record.subject === "object"
+        && record.subject !== null
+        && (record.subject as { runId?: string }).runId === runId,
+    ),
   };
 }
 
 /** Optional court-turn scope for settlement reads (#637). */
 export type SubmissionLedgerReadScope = {
   readonly home?: string;
+  /** Durable run principal; the direct ownership coordinate when already known. */
+  readonly sessionParent?: string;
   /**
    * Recording tag for this court. Presentation of original payloads is run-scoped
    * (#836: attempt/latest must not hide already-recorded rows).
@@ -178,9 +224,9 @@ export async function hasFreshAttemptSubmission(
   cwd: string,
   runId: string,
   attemptId: string,
-  home?: string,
+  homeOrScope?: string | SubmissionLedgerReadScope,
 ): Promise<boolean> {
-  const { owned } = await readOwnedSubmissionRecords(cwd, runId, home);
+  const { owned } = await readOwnedSubmissionRecords(cwd, runId, resolveReadScope(homeOrScope));
   return owned.some((record) => {
     if (recordAttemptId(record) !== attemptId) return false;
     if (record.kind === "sealed") return true;
@@ -258,14 +304,10 @@ function rowFromPayload(
  * recorded attemptId + toolCallId so distinct court attempts stay distinct (#881).
  * `accepted` is the original payload; never rebuilt from a status/facts envelope.
  */
-export async function readRecordedSubmissionRows(
-  cwd: string,
-  runId: string,
-  homeOrScope?: string | SubmissionLedgerReadScope,
-): Promise<readonly RecordedSubmissionRow[]> {
-  const scope = resolveReadScope(homeOrScope);
-  const { owned } = await readOwnedSubmissionRecords(cwd, runId, scope.home);
-  const scoped = recordsForAttempt(owned, scope.attemptId);
+function mapOwnedToSubmissionRows(
+  owned: readonly { kind?: unknown; subject?: unknown; payload?: unknown }[],
+): readonly RecordedSubmissionRow[] {
+  const scoped = owned;
   const out: RecordedSubmissionRow[] = [];
   const indexByCall = new Map<string, number>();
   // Recover seat identity for historical non-sealed rows that omitted role (#881).
@@ -360,6 +402,43 @@ export async function readRecordedSubmissionRows(
   return out;
 }
 
+/**
+ * All recorded role submissions in ledger order (#836 multi-submit).
+ * `accepted` is the original payload; never rebuilt from a status/facts envelope.
+ * Presentation stays run-scoped: attemptId on the read scope is a recording tag,
+ * not a visibility gate (#836).
+ */
+export async function readRecordedSubmissionRows(
+  cwd: string,
+  runId: string,
+  homeOrScope?: string | SubmissionLedgerReadScope,
+): Promise<readonly RecordedSubmissionRow[]> {
+  const scope = resolveReadScope(homeOrScope);
+  const { owned } = await readOwnedSubmissionRecords(cwd, runId, scope);
+  const scoped = recordsForAttempt(owned, scope.attemptId);
+  return mapOwnedToSubmissionRows(scoped);
+}
+
+/**
+ * Settlement-only this-court rows (#879 return path).
+ * Filters by attemptId for court-scoped roleOutcome; does not replace the
+ * run-scoped presentation API above (#836 visibility gate stays pass-through).
+ */
+export async function readAttemptScopedSubmissionRows(
+  cwd: string,
+  runId: string,
+  attemptId: string,
+  home?: string,
+): Promise<readonly RecordedSubmissionRow[]> {
+  if (attemptId.length === 0) return [];
+  const { owned } = await readOwnedSubmissionRecords(
+    cwd,
+    runId,
+    home === undefined ? {} : { home },
+  );
+  return mapOwnedToSubmissionRows(owned.filter((record) => recordAttemptId(record) === attemptId));
+}
+
 /**
  * All raw role payloads in ledger order (#836 multi-submit).
  * Returns `accepted` bytes as stored — unknown, never re-wrapped.
@@ -390,7 +469,7 @@ export async function readLatestSubmissionOutcome(
   homeOrScope?: string | SubmissionLedgerReadScope,
 ): Promise<LatestSubmissionOutcome | undefined> {
   const scope = resolveReadScope(homeOrScope);
-  const { owned } = await readOwnedSubmissionRecords(cwd, runId, scope.home);
+  const { owned } = await readOwnedSubmissionRecords(cwd, runId, scope);
   const scoped = recordsForAttempt(owned, scope.attemptId);
   for (let index = scoped.length - 1; index >= 0; index -= 1) {
     const record = scoped[index];
@@ -405,14 +484,35 @@ export async function readLatestSubmissionOutcome(
 
 type LedgerState = { prior?: RecordPointer; sequence: number };
 
-async function restoreState(cwd: string, runId: string, home?: string): Promise<LedgerState> {
-  const { file, owned } = await readOwnedSubmissionRecords(cwd, runId, home);
+async function restoreState(cwd: string, runId: string, scope: SubmissionLedgerReadScope): Promise<LedgerState> {
+  const located = await readOwnedSubmissionRecords(cwd, runId, scope);
+  // Unknown-run empty set: no prior chain. Owned rows without a file are an internal bug.
+  if (located.file === undefined) {
+    if (located.owned.length !== 0) {
+      throw new Error(
+        `submission ledger invariant: owned rows present without recordFile for run ${runId}`,
+      );
+    }
+    return { sequence: 0 };
+  }
+  const { file, owned } = located;
   const last = owned.at(-1);
   return {
-    ...(last === undefined ? {} : { prior: { identity: last.identity, recordFile: file, kind: last.kind, level: last.level } }),
+    ...(last === undefined
+      ? {}
+      : {
+          prior: {
+            identity: last.identity,
+            recordFile: file,
+            kind: last.kind,
+            level: last.level,
+          },
+        }),
     sequence: owned.reduce((maximum, record) => {
       const payload = record.payload as Partial<SubmissionLedgerEvent> | undefined;
-      return payload?.type === "candidate" && typeof payload.sequence === "number" ? Math.max(maximum, payload.sequence) : maximum;
+      return payload?.type === "candidate" && typeof payload.sequence === "number"
+        ? Math.max(maximum, payload.sequence)
+        : maximum;
     }, 0),
   };
 }
@@ -431,21 +531,38 @@ export function createSubmissionLedgerHost(
   options?: { home?: string },
 ): RoleHost {
   const states = new Map<string, Promise<LedgerState>>();
+  /** Sole HostContext-derived run coordinate for restore and append (never process.env). */
+  const sessionParentFromContext = (context: HostContext): string | undefined => {
+    const runDirectory = runDirectoryFromHostContext(context);
+    if (runDirectory !== undefined) {
+      return join(runDirectory, "session", "session.jsonl");
+    }
+    const sessionFile = context.sessionManager.getSessionFile?.();
+    if (typeof sessionFile === "string" && sessionFile.length > 0) return sessionFile;
+    const sessionDir = context.sessionManager.getSessionDir?.();
+    if (typeof sessionDir === "string" && sessionDir.length > 0) {
+      return join(sessionDir, "session.jsonl");
+    }
+    return undefined;
+  };
   const resolveHomeFromContext = (context: HostContext): string | undefined => {
     if (options?.home !== undefined) return options.home;
-    const sessionFile = context.sessionManager.getSessionFile?.() || context.sessionManager.getSessionDir?.();
-    return typeof sessionFile === "string" && sessionFile.length > 0
-      ? tryHomeFromAkRolesPath(sessionFile)
-      : undefined;
+    const sessionParent = sessionParentFromContext(context);
+    return sessionParent !== undefined ? tryHomeFromAkRolesPath(sessionParent) : undefined;
   };
   const stateFor = (context: HostContext, runId: string) => states.get(runId) ?? (() => {
     const home = resolveHomeFromContext(context);
-    const pending = restoreState(context.cwd, runId, home);
+    const sessionParent = sessionParentFromContext(context);
+    const pending = restoreState(context.cwd, runId, {
+      ...(home === undefined ? {} : { home }),
+      ...(sessionParent === undefined ? {} : { sessionParent }),
+    });
     states.set(runId, pending);
     return pending;
   })();
   const appendFor = (state: LedgerState, context: HostContext, runId: string, attemptId: string, event: SubmissionLedgerEvent): RecordPointer => {
     const home = resolveHomeFromContext(context);
+    const sessionParent = sessionParentFromContext(context);
     const pointer = sitianReport({
       level: "event",
       kind: event.type,
@@ -455,6 +572,7 @@ export function createSubmissionLedgerHost(
       source: "role-runtime",
       cwd: context.cwd,
       ...(home !== undefined ? { home } : {}),
+      ...(sessionParent === undefined ? {} : { sessionParent }),
     });
     state.prior = pointer;
     return pointer;

package/src/ticket-provenance.ts

@@ -13,6 +13,7 @@ import {
   type RecordPointer,
   type SitianRecord,
 } from "./sitian-facade.ts";
+import { isSafePositiveTicketNumber } from "./run-ticket-number.ts";
 import {
   TICKET_PROVENANCE_HUMAN_VIEW,
   TICKET_PROVENANCE_KIND,
@@ -25,7 +26,7 @@ import {
 
 /** Subject string for ticket-keyed volumes — history follows the ticket. */
 export function ticketProvenanceSubject(ticketNumber: number): string {
-  if (!Number.isSafeInteger(ticketNumber) || ticketNumber < 1) {
+  if (!isSafePositiveTicketNumber(ticketNumber)) {
     throw new Error(`ticket-provenance subject requires a positive ticket number, got ${String(ticketNumber)}`);
   }
   return String(ticketNumber);
@@ -57,6 +58,7 @@ export function ticketProvenanceEntryIdentity(
 export type AppendTicketProvenanceInput = {
   readonly ticketNumber: number;
   readonly cwd: string;
+  readonly sessionParent: string;
   /** Original diarist row (or `{ original, unprojected: true }` envelope). */
   readonly payload: unknown;
   /** Explicit package home (tests / admitted run); never process.env.HOME (#604). */
@@ -107,6 +109,7 @@ export function appendTicketProvenanceEntry(
     identity,
     subject,
     cwd: input.cwd,
+    sessionParent: input.sessionParent,
     ...(input.home === undefined ? {} : { home: input.home }),
     host: input.host ?? "diarist",
     source: input.source ?? "diarist",

package/src/ticket-trajectory.ts

@@ -29,6 +29,8 @@ import {
   formatTokensCompact,
   formatUsdPrecise,
 } from "./human-format.ts";
+import { listBookRunDirectories } from "./role-run-placement.ts";
+import { readRunTicketNumber } from "./run-ticket-number.ts";
 import {
   extractSessionTimestampSpan,
   readLedgerSessionJsonl,
@@ -302,16 +304,12 @@ async function readInvocation(runDir: string): Promise<InvocationInfo | undefine
         info.model = rawModel;
       }
     }
-    if (
-      typeof parsed.ticketNumber === "number" &&
-      Number.isInteger(parsed.ticketNumber) &&
-      parsed.ticketNumber >= 1
-    ) {
-      info.ticketNumber = parsed.ticketNumber;
-    }
     if (typeof parsed.correlationId === "string" && parsed.correlationId.trim() !== "") {
       info.correlationId = parsed.correlationId;
     }
+    // Display placement: board pages first, then migration-derived (never forges board).
+    const ticketNumber = await readRunTicketNumber(runDir);
+    if (ticketNumber !== undefined) info.ticketNumber = ticketNumber;
     return info;
   } catch (error) {
     // Only genuine absence activates the invocation fallback. Malformed JSON and
@@ -656,56 +654,47 @@ ${stationBlocks || "<p data-empty=\"true\">no runs</p>"}
  * Load one ticket's runs via the S1 tracer path (read-only ledger scan).
  * Factory board reuses this — no parallel receipt parser.
  *
- * Flat-run attribution (#176 option A): read typed `ticketNumber` from each
- * `runs/<run>@<role>/invocation.json`. Legacy `issues/<N>/runs` remains a
- * read-only compatibility entrance. Unbound flat runs never join a ticket.
+ * Book-run attribution (#176 / #859): read typed `ticketNumber` from each run's
+ * invocation.json under listBookRunDirectories (flat legacy `runs/` + subject-tree
+ * `<ticket|unbound>/runs/`). Legacy `issues/<N>/runs` remains a read-only
+ * compatibility entrance. Unbound runs never join a ticket.
  */
 
-/** One flat run's typed binding projection from invocation.json. */
+/** One book run's typed binding projection from invocation.json. */
 export type FlatRunTicketBinding = {
   readonly runDir: string;
   readonly runFolder: string;
+  /** Book-relative coord (e.g. `runs/id@role` or `582/runs/id@role`). */
+  readonly ledgerCoord: string;
   readonly ticketNumber?: number;
   readonly role?: string;
   readonly correlationId?: string;
 };
 
 /**
- * Book-level flat-run index built once per lane/render and reused per ticket.
- * Pure derived view of flat runs' invocation.json files — not a parallel ledger.
+ * Book-level run index built once per lane/render and reused per ticket.
+ * Pure derived view of book runs' invocation.json files — not a parallel ledger.
  */
 export type TicketTrajectoryBookIndex = {
-  /** ticket number → flat runs bound via invocation.json ticketNumber. */
+  /** ticket number → runs bound via invocation.json ticketNumber. */
   readonly runsByTicket: ReadonlyMap<number, readonly FlatRunTicketBinding[]>;
-  /** Flat runs with no typed ticketNumber (unknown/unbound seam). */
+  /** Runs with no typed ticketNumber (unknown/unbound seam). */
   readonly unboundRuns: readonly FlatRunTicketBinding[];
 };
 
-async function listFlatRunDirectories(ledgerDir: string): Promise<string[]> {
-  const runsDir = join(resolve(ledgerDir), "runs");
-  try {
-    const entries = await readdir(runsDir, { withFileTypes: true });
-    return entries
-      .filter((entry) => entry.isDirectory())
-      .map((entry) => join(runsDir, entry.name))
-      .sort();
-  } catch (error) {
-    if (isMissingPathError(error)) return [];
-    throw error;
-  }
-}
-
 export async function buildTicketTrajectoryBookIndex(
   ledgerDir: string,
 ): Promise<TicketTrajectoryBookIndex> {
   const root = resolve(ledgerDir);
   const runsByTicket = new Map<number, FlatRunTicketBinding[]>();
   const unboundRuns: FlatRunTicketBinding[] = [];
-  for (const runDir of await listFlatRunDirectories(root)) {
+  for (const runDir of await listBookRunDirectories(root)) {
     const invocation = await readInvocation(runDir);
+    const rel = relative(root, runDir).split(sep).join("/");
     const binding: FlatRunTicketBinding = {
       runDir,
       runFolder: basename(runDir),
+      ledgerCoord: rel,
       ...(invocation?.ticketNumber !== undefined
         ? { ticketNumber: invocation.ticketNumber }
         : {}),
@@ -744,8 +733,7 @@ export async function loadUnboundTrajectoryRuns(
   const index = bookIndex ?? (await buildTicketTrajectoryBookIndex(root));
   const out: UnboundTrajectoryRun[] = [];
   for (const binding of index.unboundRuns) {
-    const ledgerCoord = ["runs", binding.runFolder].join("/");
-    const run = await parseRunDirectory(binding.runDir, ledgerCoord);
+    const run = await parseRunDirectory(binding.runDir, binding.ledgerCoord);
     out.push({
       run,
       role: binding.role ?? run.station,
@@ -781,14 +769,13 @@ export async function loadTicketTrajectoryRuns(
     runs.push(parsed);
   }
 
-  // Flat runs bound by typed invocation.json ticketNumber.
+  // Book runs (flat + subject-tree) bound by typed invocation.json ticketNumber.
   const flatBindings = index.runsByTicket.get(issueNumber) ?? [];
   for (const binding of flatBindings) {
     const resolvedRunDir = resolve(binding.runDir);
     if (seenRunDirs.has(resolvedRunDir)) continue;
     seenRunDirs.add(resolvedRunDir);
-    const ledgerCoord = ["runs", binding.runFolder].join("/");
-    runs.push(await parseRunDirectory(binding.runDir, ledgerCoord));
+    runs.push(await parseRunDirectory(binding.runDir, binding.ledgerCoord));
   }
 
   return runs;

package/src/user-dialogue-stdin.ts

@@ -0,0 +1,37 @@
+/**
+ * Typed user-dialogue stdin transport (#879 / #471).
+ * Pi's piped-stdin reader trims the wrapper; the body field keeps original bytes.
+ * No size cap and no path/pointer substitute — the whole dialogue rides the envelope.
+ */
+export const USER_DIALOGUE_STDIN_KIND = "ak-user-dialogue" as const;
+
+export type UserDialogueStdinEnvelope = {
+  readonly kind: typeof USER_DIALOGUE_STDIN_KIND;
+  readonly body: string;
+};
+
+export function encodeUserDialogueStdin(body: string): string {
+  return JSON.stringify({ kind: USER_DIALOGUE_STDIN_KIND, body } satisfies UserDialogueStdinEnvelope);
+}
+
+function isUserDialogueEnvelope(value: unknown): value is UserDialogueStdinEnvelope {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const record = value as { kind?: unknown; body?: unknown };
+  return record.kind === USER_DIALOGUE_STDIN_KIND && typeof record.body === "string";
+}
+
+/**
+ * Host read: recover original dialogue after a trim-capable pipe.
+ * Non-envelope text (interactive Pi, officer JSON, headless raw body) is unchanged.
+ */
+export function readUserDialogueStdin(raw: string): string {
+  const trimmed = raw.trim();
+  if (!trimmed.startsWith("{")) return raw;
+  try {
+    const parsed: unknown = JSON.parse(trimmed);
+    if (isUserDialogueEnvelope(parsed)) return parsed.body;
+  } catch {
+    // Not our envelope — leave caller bytes intact.
+  }
+  return raw;
+}

package/src/worker-role.ts

@@ -145,8 +145,8 @@ export type CoderRoleDependencies = {
 
 export type WorkerRoleRuntime = {
   activate(ctx?: HostContext): Promise<void>;
-  /** Arm gate ① baseline after envelope places the worktree (coder/fixer). Parent feeds archivist durability. */
-  armSubmissionGate(cwd: string, parent?: { getSessionFile(): string | undefined }): void;
+  /** Arm gate ① baseline after envelope places the worktree (coder/fixer). Durable parent required (#857). */
+  armSubmissionGate(cwd: string, parent: { getSessionFile(): string | undefined }): void;
 };
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -290,6 +290,8 @@ export function createFixerRoleRuntime(
                 ...(_signal === undefined ? {} : { signal: _signal }),
                 hostActions,
                 toolCallId,
+                // #879: this-turn typed payload — identity-bound at submit site.
+                submission: output,
               });
             }
             const acceptedDetails = output;
@@ -326,7 +328,7 @@ export function createFixerRoleRuntime(
         });
       }
     },
-    armSubmissionGate(cwd: string, parent?: { getSessionFile(): string | undefined }) {
+    armSubmissionGate(cwd: string, parent: { getSessionFile(): string | undefined }) {
       submissionGate.arm(cwd, parent);
     },
   };
@@ -428,6 +430,8 @@ export function createCoderRoleRuntime(
                 ...(_signal === undefined ? {} : { signal: _signal }),
                 hostActions,
                 toolCallId,
+                // #879: this-turn typed payload — identity-bound at submit site.
+                submission: output,
               });
             }
             const acceptedDetails = output;
@@ -473,7 +477,7 @@ export function createCoderRoleRuntime(
         });
       }
     },
-    armSubmissionGate(cwd: string, parent?: { getSessionFile(): string | undefined }) {
+    armSubmissionGate(cwd: string, parent: { getSessionFile(): string | undefined }) {
       submissionGate.arm(cwd, parent);
     },
   };

package/src/worker-submission-gates.ts

@@ -221,9 +221,8 @@ function reliableWindow(
 
 export type CreateWorkerSubmissionGateOptions = {
   /**
-   * Explicit package home for sitian writes when no parent session is armed.
-   * Existing injection point on sitianReport — does not change fallback when omitted
-   * (path-derive from parent, else package machine home). #604 Scope 2.
+   * Explicit package home for sitian writes (tests / admitted run).
+   * Path still derives from required parent session; home only pins ledger root. #604 Scope 2.
    */
   readonly home?: string;
 };
@@ -231,7 +230,8 @@ export type CreateWorkerSubmissionGateOptions = {
 export function createWorkerSubmissionGate(
   options: CreateWorkerSubmissionGateOptions = {},
 ): {
-  arm(cwd: string, parent?: WorkerSubmissionGateParent): void;
+  /** Durable parent is required — ownership must be known at arm (#857 loud failure). */
+  arm(cwd: string, parent: WorkerSubmissionGateParent): void;
   assertAcceptable(status: string, details?: unknown): void;
 } {
   let baseline: string | null | undefined;
@@ -267,11 +267,11 @@ export function createWorkerSubmissionGate(
     arm(cwd, parent) {
       uninstallPackageWorkerHooks(cwd);
       root = cwd;
-      sessionParent = parent?.getSessionFile();
+      sessionParent = parent.getSessionFile();
       record = createRecordSession({
         cwd,
         kind: WORKER_SUBMISSION_GATE_RECORD_KIND,
-        ...(parent === undefined ? {} : { parent }),
+        parent,
       });
       const prior = readGateState(record);
       if (prior.baseline !== undefined) {