@akagilnc/pi-workflow-roles 0.1.4243 → 0.1.4274

package/src/engine-detour-usage.ts

@@ -0,0 +1,373 @@
+/**
+ * #537 typed ak_engine_detour tool usage ledger.
+ *
+ * Observes only the package detour tool path. Bash/CLI ordinary path
+ * (resources/engine-dispatch.md ordinary path) stays outside this ledger — a
+ * permanent blind spot that must never be read as "the seat did not use an engine".
+ *
+ * Runtime owns these facts beside role payloads (ADR 0042); they land in
+ * TerminalResult.decisiveFacts and are written live via sitian (ADR 0077).
+ * No gate, no required field, no index bytes (ADR 0049 / 0057).
+ *
+ * Invocation scope is one public ak-role call (#537), owned by the shared Host
+ * execution envelope (RoleTurnRequest / HostContext). Auto-resume attempts inside
+ * that call share the same scope; only an explicit new public call (including
+ * `ak-role resume`) mints a new one. Never courtAttemptId, never Pi session
+ * toolResult join keys, and never a detour-owned sidecar file.
+ */
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { ENGINE_DETOUR_TOOL_NAME } from "./engine-detour.ts";
+import {
+  readSitianRecords,
+  resolveSitianRecordPath,
+  sitianReport,
+  type RecordPointer,
+} from "./sitian-facade.ts";
+
+/** Sitian event kind for one detour-tool call (volume under session/). */
+export const ENGINE_DETOUR_CALL_KIND = "engine-detour-call" as const;
+
+/** decisiveFacts key — name states detour-tool scope, not full engine usage. */
+export const ENGINE_DETOUR_TOOL_USAGE_FACT_KEY = "engineDetourToolUsage" as const;
+
+/**
+ * Run-relative sitian volume path for one detour call.
+ * Openable once the run directory is known (resume.command / top-level runId);
+ * contains no runId bytes itself (#108 + #537 AC8).
+ */
+export const ENGINE_DETOUR_CALL_RECORD_FILE_RELATIVE =
+  `session/${ENGINE_DETOUR_CALL_KIND}/records.jsonl` as const;
+
+/** stdout UTF-8 byte length (ticket-frozen metric; empty stdout is real 0). */
+export function engineDetourStdoutByteLength(stdout: string): number {
+  return Buffer.byteLength(stdout, "utf8");
+}
+
+/** One observed ak_engine_detour call. code/stdoutByteLength absent on spawn failure. */
+export type EngineDetourCallFact = {
+  readonly toolCallId: string;
+  readonly durationMs: number;
+  readonly code?: number;
+  readonly stdoutByteLength?: number;
+  readonly recordPointer: Readonly<RecordPointer>;
+};
+
+/**
+ * Per-invocation aggregate for the detour tool only.
+ * callCount 0 is lawful when engine is mounted (ADR 0071 soft rule).
+ */
+export type EngineDetourToolUsageFact = {
+  readonly callCount: number;
+  readonly calls: readonly EngineDetourCallFact[];
+};
+
+export type ReportEngineDetourCallInput = {
+  readonly toolCallId: string;
+  readonly durationMs: number;
+  /** Present only when the child closed (not spawn failure). */
+  readonly code?: number;
+  /** Present only when the child closed; empty stdout → 0. */
+  readonly stdoutByteLength?: number;
+  readonly cwd: string;
+  readonly sessionParent: string;
+  readonly home?: string;
+  /** Real selected host (ADR 0077 / 0082). Never invent "pi". */
+  readonly host?: string;
+  readonly runId?: string;
+  /** Public-invocation scope id from the shared Host envelope. */
+  readonly invocationScopeId?: string;
+};
+
+/**
+ * Deterministic sitian identity: invocation scope + toolCallId.
+ * Must not embed runId — public Terminal decisiveFacts re-expose identity (#108).
+ */
+export function engineDetourCallIdentity(input: {
+  readonly toolCallId: string;
+  readonly invocationScopeId?: string;
+}): string {
+  const scope = input.invocationScopeId ?? "";
+  return `engine-detour-call:${scope}:${input.toolCallId}`;
+}
+
+/** Live sitian write for one detour call. Returns the call fact with pointer. */
+export function reportEngineDetourCall(
+  input: ReportEngineDetourCallInput,
+): EngineDetourCallFact {
+  const payload: Record<string, unknown> = {
+    tool: ENGINE_DETOUR_TOOL_NAME,
+    toolCallId: input.toolCallId,
+    durationMs: input.durationMs,
+  };
+  if (input.code !== undefined) payload.code = input.code;
+  if (input.stdoutByteLength !== undefined) {
+    payload.stdoutByteLength = input.stdoutByteLength;
+  }
+  if (input.invocationScopeId !== undefined) {
+    payload.invocationScopeId = input.invocationScopeId;
+  }
+  if (input.runId !== undefined) payload.runId = input.runId;
+
+  // SitianSubject object form requires runId; invocation scope rides payload always.
+  const subject =
+    input.runId === undefined
+      ? undefined
+      : {
+          runId: input.runId,
+          ...(input.invocationScopeId === undefined
+            ? {}
+            : { invocationScopeId: input.invocationScopeId }),
+        };
+
+  const pointer = sitianReport({
+    level: "event",
+    kind: ENGINE_DETOUR_CALL_KIND,
+    identity: engineDetourCallIdentity({
+      toolCallId: input.toolCallId,
+      ...(input.invocationScopeId === undefined
+        ? {}
+        : { invocationScopeId: input.invocationScopeId }),
+    }),
+    cwd: input.cwd,
+    sessionParent: input.sessionParent,
+    source: "engine-detour-tool",
+    payload,
+    raw: {
+      sessionFile: input.sessionParent,
+      entryId: input.toolCallId,
+    },
+    ...(input.home === undefined ? {} : { home: input.home }),
+    ...(input.host === undefined ? {} : { host: input.host }),
+    ...(subject === undefined ? {} : { subject }),
+  });
+
+  return {
+    toolCallId: input.toolCallId,
+    durationMs: input.durationMs,
+    ...(input.code === undefined ? {} : { code: input.code }),
+    ...(input.stdoutByteLength === undefined
+      ? {}
+      : { stdoutByteLength: input.stdoutByteLength }),
+    recordPointer: pointer,
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function callFactFromSitianPayload(
+  payload: unknown,
+  pointer: RecordPointer,
+): EngineDetourCallFact | undefined {
+  if (!isRecord(payload)) return undefined;
+  if (payload.tool !== ENGINE_DETOUR_TOOL_NAME) return undefined;
+  if (typeof payload.toolCallId !== "string" || payload.toolCallId.length === 0) {
+    return undefined;
+  }
+  if (typeof payload.durationMs !== "number" || !Number.isFinite(payload.durationMs)) {
+    return undefined;
+  }
+  return {
+    toolCallId: payload.toolCallId,
+    durationMs: payload.durationMs,
+    ...(typeof payload.code === "number" ? { code: payload.code } : {}),
+    ...(typeof payload.stdoutByteLength === "number"
+      ? { stdoutByteLength: payload.stdoutByteLength }
+      : {}),
+    recordPointer: pointer,
+  };
+}
+
+function invocationScopeIdOfRecord(record: {
+  readonly subject?: unknown;
+  readonly payload?: unknown;
+}): string | undefined {
+  if (isRecord(record.subject)) {
+    const fromSubject = record.subject.invocationScopeId;
+    if (typeof fromSubject === "string" && fromSubject.length > 0) return fromSubject;
+  }
+  if (isRecord(record.payload)) {
+    const fromPayload = record.payload.invocationScopeId;
+    if (typeof fromPayload === "string" && fromPayload.length > 0) return fromPayload;
+  }
+  return undefined;
+}
+
+/**
+ * Read this-invocation detour-tool usage from sitian volume.
+ * When `invocationScopeId` is provided, only records bound to that public call count
+ * (host-neutral boundary — not session toolResult join keys, not courtAttemptId).
+ * When engineMounted is false, returns undefined (field absent).
+ * When engineMounted is true and no calls, returns callCount 0.
+ */
+export async function readEngineDetourToolUsage(input: {
+  readonly sessionParent: string;
+  readonly engineMounted: boolean;
+  readonly invocationScopeId?: string;
+  readonly home?: string;
+  readonly cwd?: string;
+}): Promise<EngineDetourToolUsageFact | undefined> {
+  if (!input.engineMounted) return undefined;
+
+  const { recordFile } = resolveSitianRecordPath({
+    level: "event",
+    kind: ENGINE_DETOUR_CALL_KIND,
+    sessionParent: input.sessionParent,
+    ...(input.home === undefined ? {} : { home: input.home }),
+    ...(input.cwd === undefined ? {} : { cwd: input.cwd }),
+  });
+
+  const { records } = await readSitianRecords(recordFile);
+  const calls: EngineDetourCallFact[] = [];
+  for (const record of records) {
+    if (record.kind !== ENGINE_DETOUR_CALL_KIND) continue;
+    const boundScope = invocationScopeIdOfRecord(record);
+    if (input.invocationScopeId !== undefined && input.invocationScopeId.length > 0) {
+      if (boundScope !== input.invocationScopeId) continue;
+    } else if (boundScope !== undefined) {
+      // Unscoped settlement must not pull invocation-bound rows across resume.
+      continue;
+    }
+    const pointer: RecordPointer = {
+      identity: record.identity,
+      recordFile,
+      kind: record.kind,
+      level: record.level,
+    };
+    const fact = callFactFromSitianPayload(record.payload, pointer);
+    if (fact === undefined) continue;
+    calls.push(fact);
+  }
+
+  return { callCount: calls.length, calls };
+}
+
+/**
+ * Project usage onto the public Terminal face.
+ * Non-resumable: keep absolute recordFile (runId already public via top-level runId).
+ * Resumable: keep an openable run-relative recordFile and identity with no runId
+ * bytes (#108 single disclosure + #537 AC8 reopen).
+ */
+export function projectEngineDetourToolUsageForPublicTerminal(
+  usage: EngineDetourToolUsageFact,
+  options: { readonly discloseRecordFile: boolean },
+): EngineDetourToolUsageFact {
+  if (options.discloseRecordFile) return usage;
+  return {
+    callCount: usage.callCount,
+    calls: usage.calls.map((call) => ({
+      toolCallId: call.toolCallId,
+      durationMs: call.durationMs,
+      ...(call.code === undefined ? {} : { code: call.code }),
+      ...(call.stdoutByteLength === undefined
+        ? {}
+        : { stdoutByteLength: call.stdoutByteLength }),
+      recordPointer: {
+        identity: call.recordPointer.identity,
+        kind: call.recordPointer.kind,
+        level: call.recordPointer.level,
+        recordFile: ENGINE_DETOUR_CALL_RECORD_FILE_RELATIVE,
+      },
+    })),
+  };
+}
+
+/** One shared invocation.json reader (ENOENT → undefined; other errors propagate). */
+function readInvocationRecord(
+  runDirectory: string,
+): Record<string, unknown> | undefined {
+  try {
+    const raw = JSON.parse(
+      readFileSync(join(runDirectory, "invocation.json"), "utf8"),
+    ) as unknown;
+    return isRecord(raw) ? raw : undefined;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException)?.code === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
+/** True when invocation.json carries a non-empty engine axis. */
+export async function readInvocationEngineMounted(
+  runDirectory: string,
+): Promise<boolean> {
+  const raw = readInvocationRecord(runDirectory);
+  if (raw === undefined) return false;
+  return typeof raw.engine === "string" && raw.engine.trim() !== "";
+}
+
+/**
+ * Selected host from the admission invocation page — for post-admission
+ * host-transition classification only. In-turn tools take host from the shared
+ * Host envelope (RoleTurnRequest / HostContext), never this reader.
+ * Undefined when absent — callers must not invent "pi".
+ */
+export function readInvocationSelectedHost(runDirectory: string): string | undefined {
+  const raw = readInvocationRecord(runDirectory);
+  if (raw === undefined) return undefined;
+  return typeof raw.host === "string" && raw.host.trim() !== ""
+    ? raw.host.trim()
+    : undefined;
+}
+
+/** Merge usage into decisiveFacts without touching role payloads. */
+export function withEngineDetourToolUsageFact<
+  T extends { readonly decisiveFacts?: Readonly<Record<string, unknown>> },
+>(
+  outcome: T,
+  usage: EngineDetourToolUsageFact | undefined,
+): T {
+  if (usage === undefined) return outcome;
+  const prior = isRecord(outcome.decisiveFacts) ? outcome.decisiveFacts : {};
+  return {
+    ...outcome,
+    decisiveFacts: {
+      ...prior,
+      [ENGINE_DETOUR_TOOL_USAGE_FACT_KEY]: usage,
+    },
+  };
+}
+
+/** runDirectory owning a session directory (.../runs/<id>@role/session). */
+export function runDirectoryFromSessionDirectory(sessionDirectory: string): string {
+  return dirname(sessionDirectory);
+}
+
+/** session.jsonl under a session directory. */
+export function sessionFileFromSessionDirectory(sessionDirectory: string): string {
+  return join(sessionDirectory, "session.jsonl");
+}
+
+/**
+ * Mint one public-invocation scope id when an engine is mounted.
+ * Call once at the public-entry boundary — never inside the auto-resume loop.
+ * The id lives on RoleTurnRequest / HostContext only (no detour sidecar file).
+ */
+export function mintEngineDetourInvocationScope(input: {
+  readonly effectiveEngine?: string;
+}): string | undefined {
+  const engine = input.effectiveEngine?.trim();
+  if (engine === undefined || engine.length === 0) return undefined;
+  return randomUUID();
+}
+
+/** Attach a minted scope onto a turn request (shared Host envelope field). */
+export function withEngineDetourInvocationScope<T extends object>(
+  request: T & { readonly invocationScopeId?: string },
+  invocationScopeId: string | undefined,
+): T & { readonly invocationScopeId?: string } {
+  if (invocationScopeId === undefined || invocationScopeId.length === 0) {
+    return request;
+  }
+  if (
+    typeof request.invocationScopeId === "string" &&
+    request.invocationScopeId.length > 0
+  ) {
+    return request;
+  }
+  return { ...request, invocationScopeId };
+}

package/src/host-contracts.ts

@@ -194,6 +194,17 @@ export type RoleTurnRequest = {
    * and resume-with-message set this; bare resume without an open court omits it.
    */
   readonly courtAttemptId?: string;
+  /**
+   * Public-invocation scope (#537): one ak-role call. Auto-resume reuses it;
+   * explicit resume mints a new one. Owned by this shared Host envelope — not
+   * courtAttemptId and not a detour sidecar file.
+   */
+  readonly invocationScopeId?: string;
+  /**
+   * Selected host axis for this turn (#537 / ADR 0082). Projected from the
+   * public-entry seat resolution — never re-read from invocation.json by tools.
+   */
+  readonly host?: string;
   /** Station child role run (#840): omit automatic navigator attendance. */
   readonly stationChild?: boolean;
 };
@@ -246,7 +257,7 @@ export interface DurablePrincipalAuthority {
 type HostSessionManager = { getLeafEntry(): HostSessionEntry | undefined; getLeafId(): string | null | undefined; getEntries(): Iterable<HostSessionEntry>; getSessionDir(): string; getSessionFile(): string | undefined; getHeader?(): { readonly type: string; readonly id?: string } | null; setSessionFile?(path: string): void; appendCustomEntry?(customType: string, data?: unknown): unknown; };
 
 /** Context supplied by a host for one activation and its interceptable events. */
-export type HostContext = { cwd: string; mode: string; model: { readonly provider: string } | undefined; sessionManager: HostSessionManager; /** Per-turn admitted run directory (#879); never process-global env. */ runDirectory?: string; /** Per-turn court attempt (#879); never process-global env. */ courtAttemptId?: string; signal?: AbortSignal | undefined; ui?: { notify?(message: string, type?: "info" | "warning" | "error"): void }; transcript?(): string; abort(): void; };
+export type HostContext = { cwd: string; mode: string; model: { readonly provider: string } | undefined; sessionManager: HostSessionManager; /** Per-turn admitted run directory (#879); never process-global env. */ runDirectory?: string; /** Per-turn court attempt (#879); never process-global env. */ courtAttemptId?: string; /** Public-invocation scope (#537); never process-global env. */ invocationScopeId?: string; /** Selected host axis (#537 / ADR 0082); never process-global env invent. */ host?: string; signal?: AbortSignal | undefined; ui?: { notify?(message: string, type?: "info" | "warning" | "error"): void }; transcript?(): string; abort(): void; };
 
 /** Per-turn run directory; adapters must project any child-process identity. */
 export function runDirectoryFromHostContext(context: HostContext): string | undefined {

package/src/navigator-attendance.ts

@@ -18,7 +18,6 @@ import {
 import type { HostContext } from "./host-contracts.ts";
 import { createNativeNavigatorSessionFactory } from "./navigator-public-session.ts";
 import {
-  NAVIGATOR_DEFAULT_MODEL,
   NAVIGATOR_PREPARE_TOOL_NAME,
   NavigatorUnavailableError,
   navigatorModelSettingPath,
@@ -40,7 +39,6 @@ import {
 import { sitianReport } from "./sitian-facade.ts";
 
 export {
-  NAVIGATOR_DEFAULT_MODEL,
   NAVIGATOR_PREPARE_TOOL_NAME,
   NavigatorUnavailableError,
   navigatorModelSettingPath,

package/src/navigator-public-session.ts

@@ -12,7 +12,6 @@ import {
   navigatorProviderFailureFromError,
   navigatorUnavailableError,
   parseNavigatorModelSetting,
-  resolveNavigatorSeatSelection,
   type NavigatorProviderFailureFact,
   type NavigatorSessionFactory,
 } from "./navigator-session-contracts.ts";
@@ -43,8 +42,9 @@ async function resolveNavigatorLedgerHome(context: HostContext): Promise<string
 
 export function createNativeNavigatorSessionFactory(): NavigatorSessionFactory {
   return async ({ context, subject, tool }) => {
-    const resolved = await resolveNavigatorSeatSelection(context);
-    let thinkingLevel = resolved.thinkingLevel;
+    // Model is enforced at prepare (attendance seat resolve) and at prompt (summon).
+    // Factory open only books the archivist nest — no package default, no eager seat read.
+    let thinkingLevel: string | undefined;
 
     // Archivist nest for attendance route memory only (ADR 0018 / 0065) — not a session open.
     // #852: navigator/<work-subject> is the sole book-top exception; always pass subject so

package/src/navigator-session-contracts.ts

@@ -15,7 +15,6 @@ import type { NoReceiptLifecycleFacts } from "./receipt-delivery-policy.ts";
 
 
 export const NAVIGATOR_PREPARE_TOOL_NAME = "ak_navigator_prepare" as const;
-export const NAVIGATOR_DEFAULT_MODEL = "openai-codex/gpt-5.6-luna:max" as const;
 
 export type NavigatorUnavailableKey =
   | "context" | "session" | "model" | "thinking" | "auth" | "quota" | "transport" | "unknown";
@@ -229,8 +228,9 @@ export async function readNavigatorModelSetting(path = navigatorModelSettingPath
     }
     return raw.model;
   } catch (error) {
+    // #178: missing file is absence (no package default).
     if (error instanceof Error && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT") {
-      return NAVIGATOR_DEFAULT_MODEL;
+      throw new Error("Navigator model setting is missing");
     }
     throw error;
   }
@@ -294,19 +294,13 @@ export async function resolveNavigatorSeatSelection(
           : packageMachineHome();
     const config = await loadPublicCliConfig(home);
     const modelOnly = seatModelOnly(config.seats.navigator);
-    // Seat table is the only model authority — no legacy navigator-model.json.
-    // Bare missing seat uses the package default constant (not a file path).
+    // Seat table only — missing navigator seat → typed model-unavailable (#178).
     if (modelOnly === undefined) {
-      const parsed = parseNavigatorModelSetting(NAVIGATOR_DEFAULT_MODEL);
-      return {
-        selection: {
-          provider: parsed.provider,
-          model: parsed.model,
-          ...(parsed.thinkingLevel === undefined ? {} : { thinking: parsed.thinkingLevel }),
-        },
-        configuredLabel: NAVIGATOR_DEFAULT_MODEL,
-        ...(parsed.thinkingLevel === undefined ? {} : { thinkingLevel: parsed.thinkingLevel }),
-      };
+      const { missingResolvedSeatModelMessage } = await import("./public-cli/config.ts");
+      throw navigatorUnavailableError(
+        "model",
+        new Error(missingResolvedSeatModelMessage("navigator")),
+      );
     }
     // Host params passthrough only — no map/validate/default (#675 ⑥).
     const thinkingRaw = modelOnly.thinking;

package/src/pi/adapter.ts

@@ -52,6 +52,12 @@ function projectPiContext(context: ExtensionContext, transcriptFromContext?: (co
     ...(typeof process.env.AK_ROLE_COURT_ATTEMPT === "string" && process.env.AK_ROLE_COURT_ATTEMPT.trim() !== ""
       ? { courtAttemptId: process.env.AK_ROLE_COURT_ATTEMPT }
       : {}),
+    ...(typeof process.env.AK_ROLE_INVOCATION_SCOPE === "string" && process.env.AK_ROLE_INVOCATION_SCOPE.trim() !== ""
+      ? { invocationScopeId: process.env.AK_ROLE_INVOCATION_SCOPE }
+      : {}),
+    ...(typeof process.env.AK_ROLE_HOST === "string" && process.env.AK_ROLE_HOST.trim() !== ""
+      ? { host: process.env.AK_ROLE_HOST.trim() }
+      : {}),
     sessionManager: {
       getLeafEntry: () => context.sessionManager.getLeafEntry(),
       getLeafId: () => context.sessionManager.getLeafId(),

package/src/pi/role-turn-host.ts

@@ -447,6 +447,12 @@ export function createPiRoleTurnHost(config: PiRoleTurnHostConfig): RoleTurnHost
       };
       if (request.courtAttemptId === undefined) delete env.AK_ROLE_COURT_ATTEMPT;
       else env.AK_ROLE_COURT_ATTEMPT = request.courtAttemptId;
+      // Public-invocation scope (#537): omit must not inherit a parent env value.
+      if (request.invocationScopeId === undefined) delete env.AK_ROLE_INVOCATION_SCOPE;
+      else env.AK_ROLE_INVOCATION_SCOPE = request.invocationScopeId;
+      // Selected host axis (#537 / ADR 0082): omit must not inherit a parent env value.
+      if (request.host === undefined || request.host.trim() === "") delete env.AK_ROLE_HOST;
+      else env.AK_ROLE_HOST = request.host.trim();
       applyEngineChildEnv(env, request.engine);
       // Nested auditor dossier tool binds the parent run pointer when published.
       if (