@akagilnc/pi-workflow-roles 0.1.3545 → 0.1.3552

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

@@ -1,12 +1,8 @@
-import { execFile, spawn } from "node:child_process";
-import { copyFile, lstat, mkdir, open, realpath, rm } from "node:fs/promises";
-import { basename, dirname, isAbsolute, join, relative as pathRelative } from "node:path";
+import { spawn } from "node:child_process";
 import { createInterface } from "node:readline";
-import { promisify } from "node:util";
 
 import type { RoleTurnHost, RoleTurnKnownFailure, RoleTurnRequest, RoleTurnResult } from "../host-contracts.ts";
 import { renderAgentStartMaterials } from "../agent-start-materials.ts";
-import { installGrokPreToolUseDeny } from "./bash-seatbelt.ts";
 
 /** ACP v1 surface used by the Grok adapter. Protocol details stay in this module. */
 export interface GrokAcpConnection {
@@ -17,13 +13,6 @@ export interface GrokAcpConnection {
   close(): Promise<void>;
 }
 
-export type GrokControlledInspection = Readonly<{
-  /** Active configuration whose source is neither Grok builtin nor AK injection. */
-  privateActive: readonly string[];
-  /** Active AK-owned configuration observed by the same first-party inspect call. */
-  akActive: readonly string[];
-}>;
-
 /** The shared envelope, prepared before session/new (systemPrompt delivery) and
  * able to observe the host's real builtin tool surface once it arrives post-session. */
 export type GrokPreparedTurn = Readonly<{
@@ -63,11 +52,6 @@ export function renderGrokSystemPromptOverride(authority: {
   return renderAgentStartMaterials(authority.body, authority.materials);
 }
 
-export type GrokCapabilityDeclaration = Readonly<{
-  nativeToolNarrowing: false;
-  preToolUseDeny: boolean;
-}>;
-
 export type GrokSessionIdentityAuthority = Readonly<{
   load(principal: RoleTurnRequest["principal"]): Promise<string | undefined>;
   bind(principal: RoleTurnRequest["principal"], sessionId: string): Promise<void>;
@@ -78,9 +62,7 @@ export type GrokSessionIdentityAuthority = Readonly<{
 export type GrokRoleTurnHostConfig = Readonly<{
   sessionIdentity: GrokSessionIdentityAuthority;
   connect(request: RoleTurnRequest): Promise<GrokAcpConnection>;
-  inspect(request: RoleTurnRequest): Promise<GrokControlledInspection>;
   prepare(request: RoleTurnRequest): Promise<GrokPreparedTurn>;
-  recordCapabilities(request: RoleTurnRequest, declaration: GrokCapabilityDeclaration): void | Promise<void>;
 }>;
 
 function failure(cause: "activation" | "session" | "output", name: string, code: string, details?: Readonly<Record<string, unknown>>): RoleTurnResult {
@@ -223,21 +205,13 @@ export function createGrokRoleTurnHost(config: GrokRoleTurnHostConfig): RoleTurn
   return {
     executeTurn(request) {
       const execution = serial.then(async (): Promise<RoleTurnResult> => {
-        const inspected = await config.inspect(request);
-        if (inspected.privateActive.length !== 0) {
-          return failure("activation", "UncontrolledGrokSession", "private-config-active", {
-            privateActive: [...inspected.privateActive],
-          });
-        }
         const continuation = request.continuation;
         const prepared = await config.prepare(request);
         let connection: GrokAcpConnection | undefined;
         let sessionId: string | undefined;
         let accepted = false;
         try {
-          // AK injection proof is prepared MCP composition (envelope), not inspect.akActive.
-          // Inspect only classifies first-party already-active sources; external packageRoot
-          // materials reach session/new via prepare, not via Grok-native inspect paths.
+          // AK injection proof is prepared MCP composition (envelope).
           if (prepared.mcpServers.length === 0) {
             return failure("activation", "UncontrolledGrokSession", "ak-config-missing");
           }
@@ -249,20 +223,6 @@ export function createGrokRoleTurnHost(config: GrokRoleTurnHostConfig): RoleTurn
           const initializeMeta = initialized._meta as {
             modelState?: { availableModels?: unknown };
           } | undefined;
-          const hookMeta = initialized._meta as { "x.ai/hooks"?: { blockingEvents?: unknown; decisions?: unknown } } | undefined;
-          const hookCapability = hookMeta?.["x.ai/hooks"];
-          const canDeny = Array.isArray(hookCapability?.blockingEvents)
-            && hookCapability.blockingEvents.includes("pre_tool_use")
-            && Array.isArray(hookCapability.decisions)
-            && hookCapability.decisions.includes("deny");
-          // ADR 0008: seatbelt hangs only on the activated Fixer. Capability alone
-          // is not an installed belt, and review seats (ADR 0064) must stay unnarrowed.
-          let preToolUseDeny = false;
-          if (canDeny && request.activation.role === "fixer") {
-            await installGrokPreToolUseDeny(request.home);
-            preToolUseDeny = true;
-          }
-          await config.recordCapabilities(request, { nativeToolNarrowing: false, preToolUseDeny });
           const modelState = initializeMeta?.modelState;
           const availableModels = Array.isArray(modelState?.availableModels) ? modelState.availableModels : undefined;
           if (request.model !== undefined && availableModels !== undefined && !availableModels.some((entry) =>
@@ -436,325 +396,11 @@ const PRIVATE_COMPAT_ENV = Object.fromEntries(
       [`GROK_${vendor}_${kind}_ENABLED`, "false"] as const)),
 );
 
-type InspectItem = {
-  readonly name?: unknown;
-  readonly path?: unknown;
-  readonly disabled?: unknown;
-  readonly enabled?: unknown;
-  readonly compatibilityStatus?: unknown;
-  readonly source?: { readonly type?: unknown; readonly path?: unknown };
-};
-
-export type GrokInspectionClassificationOptions = Readonly<{
-  /**
-   * Calling-repo projectInstructions whose path is carried by HEAD and whose
-   * working-tree bytes match that blob (#521 repo-instructions-are-shared-material).
-   * These are shared repo material — not privateActive, not AK package injection.
-   */
-  readonly headMatchedProjectInstructionPaths?: ReadonlySet<string>;
-}>;
-
-const execFileAsync = promisify(execFile);
-
-function errnoCode(error: unknown): string | undefined {
-  if (typeof error !== "object" || error === null || !("code" in error)) return undefined;
-  const code = (error as { code: unknown }).code;
-  return typeof code === "string" ? code : undefined;
-}
-
-async function realpathIfPresent(path: string): Promise<string | undefined> {
-  try {
-    return await realpath(path);
-  } catch (error) {
-    if (errnoCode(error) === "ENOENT") return undefined;
-    throw error;
-  }
-}
-
-/**
- * Typed worktree readability: ENOENT → absent; permission and other IO stay loud.
- * Does not consult Git diagnostics.
- */
-async function worktreeFilePresence(path: string): Promise<"absent" | "present"> {
-  try {
-    const handle = await open(path, "r");
-    await handle.close();
-    return "present";
-  } catch (error) {
-    if (errnoCode(error) === "ENOENT") return "absent";
-    throw error;
-  }
-}
-
-/**
- * Map a worktree-relative path to the unique HEAD tree path it names.
- * Exact match first; otherwise a single case-insensitive hit in the same
- * directory (Grok may report `Claude.md` while HEAD stores `CLAUDE.md`).
- * Path identity keeps the inspect leaf name (final symlink not followed).
- * Git/IO failures propagate; only "not in HEAD" returns undefined.
- */
-async function resolveHeadTreePath(topLevel: string, relativePath: string): Promise<string | undefined> {
-  const { stdout: exactOut } = await execFileAsync(
-    "git",
-    ["ls-tree", "--name-only", "HEAD", "--", relativePath],
-    { cwd: topLevel, encoding: "utf8" },
-  );
-  const exactHits = exactOut.split("\n").map((name) => name.trim()).filter((name) => name !== "");
-  if (exactHits.includes(relativePath)) return relativePath;
-
-  const parent = dirname(relativePath);
-  const leaf = basename(relativePath);
-  // Path absence is an empty structured ls-tree result (exit 0), never stderr prose.
-  if (parent !== ".") {
-    const { stdout: parentOut } = await execFileAsync(
-      "git",
-      ["ls-tree", "--name-only", "HEAD", "--", parent],
-      { cwd: topLevel, encoding: "utf8" },
-    );
-    const parentHits = parentOut.split("\n").map((name) => name.trim()).filter((name) => name !== "");
-    if (!parentHits.includes(parent)) return undefined;
-  }
-
-  // Parent confirmed present (or root): list children. Any failure stays loud infrastructure.
-  const { stdout: listing } = parent === "."
-    ? await execFileAsync("git", ["ls-tree", "--name-only", "HEAD"], {
-      cwd: topLevel,
-      encoding: "utf8",
-    })
-    : await execFileAsync("git", ["ls-tree", "--name-only", `HEAD:${parent}`], {
-      cwd: topLevel,
-      encoding: "utf8",
-    });
-  const needle = leaf.toLowerCase();
-  const hits = listing
-    .split("\n")
-    .map((name) => name.trim())
-    .filter((name) => name !== "" && basename(name).toLowerCase() === needle)
-    .map((name) => (parent === "." ? basename(name) : join(parent, basename(name))));
-  return hits.length === 1 ? hits[0] : undefined;
-}
-
-/**
- * True when inspect-reported path is carried by calling-repo HEAD and the bytes
- * a host reads through that path match the HEAD blob
- * (#521 repo-instructions-are-shared-material).
- *
- * Expected negatives (return false): empty/outside path, HEAD does not carry
- * the path, worktree absent, or worktree bytes ≠ HEAD blob.
- * Infrastructure (throw with cause): git unavailable, unexpected git/repo
- * failure, permission or other IO on realpath/hash.
- */
-export async function isHeadMatchedProjectInstruction(
-  repositoryCwd: string,
-  absolutePath: string,
-): Promise<boolean> {
-  if (absolutePath === "" || absolutePath.includes("\0")) return false;
-
-  const { stdout: topLevelOut } = await execFileAsync("git", ["rev-parse", "--show-toplevel"], {
-    cwd: repositoryCwd,
-    encoding: "utf8",
-  });
-  // Prove HEAD is readable before path negatives — corrupt/missing HEAD stays loud.
-  await execFileAsync("git", ["rev-parse", "--verify", "HEAD"], {
-    cwd: repositoryCwd,
-    encoding: "utf8",
-  });
-  const topLevel = await realpath(topLevelOut.trim());
-
-  // Keep final leaf identity (do not realpath through a final-component symlink).
-  const parent = await realpathIfPresent(dirname(absolutePath));
-  if (parent === undefined) return false;
-  const leaf = basename(absolutePath);
-  if (leaf === "" || leaf === "." || leaf === "..") return false;
-  const candidate = join(parent, leaf);
-  const relative = pathRelative(topLevel, candidate);
-  if (relative === "" || relative.startsWith("..") || isAbsolute(relative) || relative.includes("\0")) {
-    return false;
-  }
-
-  const headRel = await resolveHeadTreePath(topLevel, relative);
-  if (headRel === undefined) return false;
-  const headFile = join(topLevel, headRel);
-
-  const { stdout: headBlobOut } = await execFileAsync(
-    "git",
-    ["rev-parse", "--verify", `HEAD:${headRel}`],
-    { cwd: topLevel, encoding: "utf8" },
-  );
-  const headBlob = headBlobOut.trim();
-
-  // Prefer inspect-reported path bytes (hash-object follows symlink content).
-  // Worktree absence is typed FS ENOENT; permission and other IO stay loud.
-  // When exact casing is absent, fall back to the unique HEAD-cased path.
-  let hashTarget = candidate;
-  const candidatePresence = await worktreeFilePresence(candidate);
-  if (candidatePresence === "absent") {
-    if (candidate === headFile) return false;
-    const headPresence = await worktreeFilePresence(headFile);
-    if (headPresence === "absent") return false;
-    hashTarget = headFile;
-  }
-  const { stdout } = await execFileAsync("git", ["hash-object", "--", hashTarget], {
-    cwd: topLevel,
-    encoding: "utf8",
-  });
-  return headBlob === stdout.trim();
-}
-
-function inspectItemPath(value: InspectItem): string {
-  if (typeof value.source?.path === "string") return value.source.path;
-  if (typeof value.path === "string") return value.path;
-  return "";
-}
-
-function isInspectItemActive(value: InspectItem): boolean {
-  return value.disabled !== true && value.enabled !== false && value.compatibilityStatus !== "disabled";
-}
-
-/** Collect active projectInstruction paths for HEAD-blob provenance resolution. */
-export function listActiveProjectInstructionPaths(document: Readonly<Record<string, unknown>>): readonly string[] {
-  const items = document.projectInstructions;
-  if (!Array.isArray(items)) return [];
-  const paths: string[] = [];
-  for (const value of items as InspectItem[]) {
-    if (!isInspectItemActive(value)) continue;
-    const path = inspectItemPath(value);
-    if (path !== "") paths.push(path);
-  }
-  return paths;
-}
-
-/** Classify first-party inspect JSON by provenance; wording and item counts are irrelevant. */
-export function classifyGrokInspection(
-  document: Readonly<Record<string, unknown>>,
-  packageRoot: string,
-  options: GrokInspectionClassificationOptions = {},
-): GrokControlledInspection {
-  const privateActive = new Set<string>();
-  const akActive = new Set<string>();
-  const headMatched = options.headMatchedProjectInstructionPaths ?? new Set<string>();
-  const externalCompat = document.externalCompat as { cells?: unknown } | undefined;
-  if (Array.isArray(externalCompat?.cells)) {
-    for (const cell of externalCompat.cells as Array<{ vendor?: unknown; surface?: unknown; enabled?: unknown }>) {
-      if (cell.enabled !== true) continue;
-      privateActive.add(`externalCompat:${String(cell.vendor)}:${String(cell.surface)}`);
-    }
-  }
-  for (const section of ["skills", "agents", "plugins", "mcpServers", "hooks", "projectInstructions"] as const) {
-    const items = document[section];
-    if (!Array.isArray(items)) continue;
-    for (const value of items as InspectItem[]) {
-      if (!isInspectItemActive(value)) continue;
-      const sourceType = value.source?.type;
-      const path = inspectItemPath(value);
-      const identity = `${section}:${typeof value.name === "string" ? value.name : path}`;
-      if (sourceType === "builtin" || sourceType === "bundled") continue;
-      if (path === packageRoot || path.startsWith(`${packageRoot}/`)) akActive.add(identity);
-      else if (section === "projectInstructions" && headMatched.has(path)) continue;
-      else privateActive.add(identity);
-    }
-  }
-  return { privateActive: [...privateActive].sort(), akActive: [...akActive].sort() };
-}
-
-/** AK Fixer PreToolUse seatbelt files written under controlled GROK_HOME/hooks. */
-export const AK_BASH_SEATBELT_HOOK_FILES = ["ak-bash-seatbelt.json", "ak-bash-seatbelt.mjs"] as const;
-
-function isMissingPathError(error: unknown): boolean {
-  return error instanceof Error && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR");
-}
-
-/** Refuse symlink roots so copy/rm never follow a redirected controlled home (#594 F4). */
-export async function assertControlledGrokHomeIsRealDirectory(controlledHome: string): Promise<void> {
-  let st;
-  try {
-    st = await lstat(controlledHome);
-  } catch (error) {
-    if (isMissingPathError(error)) return;
-    throw error;
-  }
-  if (st.isSymbolicLink()) {
-    throw new Error(`controlled grok home must not be a symlink: ${controlledHome}`);
-  }
-  if (!st.isDirectory()) {
-    throw new Error(`controlled grok home must be a real directory: ${controlledHome}`);
-  }
-}
-
-/** Refuse a symlink credential destination before copy or scrub (#594 F4). */
-export async function assertControlledGrokAuthIsNotSymlink(authPath: string): Promise<void> {
-  let st;
-  try {
-    st = await lstat(authPath);
-  } catch (error) {
-    if (isMissingPathError(error)) return;
-    throw error;
-  }
-  if (st.isSymbolicLink()) {
-    throw new Error(`controlled grok auth must not be a symlink: ${authPath}`);
-  }
-}
-
-/** Remove AK seatbelt hook residue while leaving sessions/ intact (#594 F1). */
-export async function scrubAkBashSeatbeltHooks(controlledHome: string): Promise<void> {
-  const hooksDir = join(controlledHome, "hooks");
-  for (const name of AK_BASH_SEATBELT_HOOK_FILES) {
-    await rm(join(hooksDir, name), { force: true });
-  }
-}
-
-/**
- * Copy only Grok's authentication authority into an otherwise isolated home.
- * Refuses symlink home/auth destinations (no follow). Scrubs crash-window residual
- * auth.json and AK seatbelt hooks before the copy so the next inspect cannot see
- * either residue (#594 F1/F3/F4).
- */
-export async function prepareControlledGrokHome(sourceHome: string, controlledHome: string): Promise<void> {
-  await assertControlledGrokHomeIsRealDirectory(controlledHome);
-  await mkdir(controlledHome, { recursive: true, mode: 0o700 });
-  await assertControlledGrokHomeIsRealDirectory(controlledHome);
-  const authPath = join(controlledHome, "auth.json");
-  await assertControlledGrokAuthIsNotSymlink(authPath);
-  // Crash-window residue: prior auth.json may still sit in the retained ledger.
-  await rm(authPath, { force: true });
-  await scrubAkBashSeatbeltHooks(controlledHome);
-  await copyFile(join(sourceHome, ".grok", "auth.json"), authPath);
-}
-
-/** First-party structured inspection under the exact environment used by ACP. */
-export async function inspectControlledGrok(options: {
-  readonly binary: string;
-  readonly cwd: string;
-  readonly env: NodeJS.ProcessEnv;
-  readonly packageRoot: string;
-}): Promise<GrokControlledInspection> {
-  const { stdout } = await execFileAsync(options.binary, ["inspect", "--json"], {
-    cwd: options.cwd,
-    env: options.env,
-    encoding: "utf8",
-  });
-  const document: unknown = JSON.parse(stdout);
-  if (typeof document !== "object" || document === null || Array.isArray(document)) {
-    throw new Error("Grok structured inspection did not return an object");
-  }
-  const record = document as Readonly<Record<string, unknown>>;
-  const headMatchedProjectInstructionPaths = new Set<string>();
-  for (const path of listActiveProjectInstructionPaths(record)) {
-    if (path === options.packageRoot || path.startsWith(`${options.packageRoot}/`)) continue;
-    if (await isHeadMatchedProjectInstruction(options.cwd, path)) {
-      headMatchedProjectInstructionPaths.add(path);
-    }
-  }
-  return classifyGrokInspection(record, options.packageRoot, { headMatchedProjectInstructionPaths });
-}
-
-/** Exact child environment shared by inspect and ACP agent processes. */
-export function controlledGrokChildEnv(base: NodeJS.ProcessEnv, grokHome: string): NodeJS.ProcessEnv {
+/** Child environment shared by ACP agent processes. */
+export function controlledGrokChildEnv(base: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
   return {
     ...base,
     ...PRIVATE_COMPAT_ENV,
-    HOME: grokHome,
-    GROK_HOME: grokHome,
     GROK_MEMORY: "0",
     GROK_SUBAGENTS: "0",
   };

package/src/host-transition-prior-native.ts

@@ -3,7 +3,7 @@
  * Closed host discriminators only; unknown previous/live hosts never inject.
  */
 import { access, readdir } from "node:fs/promises";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 
 import type { RoleTurnHostTransition } from "./host-contracts.ts";
 
@@ -29,42 +29,33 @@ async function listPiNativeRecordPaths(sessionFile: string): Promise<string[]> {
   }
 }
 
-/** Native Grok updates.jsonl paths under runDirectory/grok-home/sessions, sorted. */
-export async function listGrokNativeRecordPaths(runDirectory: string): Promise<string[]> {
-  const grokSessionsDir = join(runDirectory, "grok-home", "sessions");
-  let encodedCwds;
+/**
+ * Present sitian records.jsonl paths under sessionParent topology (#717).
+ * resolveSitianRecordPathInLedger writes dirname(sessionParent)/<category>/records.jsonl
+ * when sessionParent is inside ledger home — never session.jsonl itself.
+ */
+async function listSitianRecordPaths(sessionParent: string): Promise<string[]> {
+  const sessionRoot = dirname(sessionParent);
+  let entries;
   try {
-    encodedCwds = await readdir(grokSessionsDir, { withFileTypes: true });
+    entries = await readdir(sessionRoot, { withFileTypes: true });
   } catch (error) {
     if (isEnoent(error)) return [];
     throw error;
   }
-  const updatesPaths: string[] = [];
-  for (const cwdEntry of encodedCwds) {
-    if (!cwdEntry.isDirectory()) continue;
-    let sessionDirs;
-    try {
-      sessionDirs = await readdir(join(grokSessionsDir, cwdEntry.name), { withFileTypes: true });
-    } catch (error) {
-      if (isEnoent(error)) continue;
-      throw error;
-    }
-    for (const sessEntry of sessionDirs) {
-      if (!sessEntry.isDirectory()) continue;
-      updatesPaths.push(join(grokSessionsDir, cwdEntry.name, sessEntry.name, "updates.jsonl"));
-    }
-  }
-  updatesPaths.sort();
-  const present: string[] = [];
-  for (const updatesFile of updatesPaths) {
+  const recordPaths: string[] = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const recordFile = join(sessionRoot, entry.name, "records.jsonl");
     try {
-      await access(updatesFile);
-      present.push(updatesFile);
+      await access(recordFile);
+      recordPaths.push(recordFile);
     } catch (error) {
       if (!isEnoent(error)) throw error;
     }
   }
-  return present;
+  recordPaths.sort();
+  return recordPaths;
 }
 
 /**
@@ -72,13 +63,13 @@ export async function listGrokNativeRecordPaths(runDirectory: string): Promise<s
  * Unknown host names → undefined (no inject). Empty native volume still
  * yields a typed switch (empty path list).
  *
- * Grok native home lives under the live run that wrote it (#617 DK-4 / #637
- * same-run resume). No cross-run previousRunDirectory override.
+ * Pi previous → Pi session.jsonl path.
+ * Grok previous → sitian records on the live run (#717). Grok CLI journals
+ * stay in the operator grok home; they are not copied here.
  */
 export async function projectHostTransitionPriorNative(input: {
   readonly previousHost: string;
   readonly liveHost: string;
-  readonly runDirectory: string;
   readonly piSessionFile: string;
 }): Promise<RoleTurnHostTransition | undefined> {
   if (input.previousHost === input.liveHost) return undefined;
@@ -92,8 +83,8 @@ export async function projectHostTransitionPriorNative(input: {
       priorNativePaths: paths,
     };
   }
-  // previousHost === "grok-build": DK-7 path handoff only — do not read bytes.
-  const paths = await listGrokNativeRecordPaths(input.runDirectory);
+  // previousHost === "grok-build": sitian path handoff only — do not read bytes.
+  const paths = await listSitianRecordPaths(input.piSessionFile);
   return {
     previousHost: "grok-build",
     priorNativePaths: paths,

package/src/public-cli/cli.ts

@@ -294,6 +294,11 @@ export type CliEnv = {
   /** Override Notary role-run timeout (tests). */
   notaryTimeoutMs?: number;
   createRunId?: () => string;
+  /**
+   * #724: set by the `new` support verb before role dispatch; seat runners
+   * skip same-ticket auto-resume. Not a public flag — the verb is the choice.
+   */
+  freshSummons?: true;
 };
 
 /** Compose the Pi turn host for one role dispatch (sole public-cli → pi contact). */
@@ -437,6 +442,7 @@ function createRoleEnvironment(
     ...(options.config?.autoResumeLimit === undefined
       ? {}
       : { autoResumeLimit: options.config.autoResumeLimit }),
+    ...(env.freshSummons === true ? { freshSummons: true as const } : {}),
   };
 }
 
@@ -1084,12 +1090,14 @@ export async function runAkRole(
       packageRoot: await realpath(env.packageRoot),
       principalAuthority: env.principalAuthority ?? piDurablePrincipalAuthority,
     };
-    const parsed = parseArgv(argv);
-    // Host/engine axes: callable roles + resume (#617 DK-3: resume shares seat axes).
+    let parsed = parseArgv(argv);
+    // Host/engine axes: callable roles + resume + new (#617 DK-3; #724 new shares seat axes).
     // Support commands (roles/config/…) still refuse both flags.
     const acceptsSeatAxes =
       parsed.command !== undefined &&
-      (isPublicCallableRole(parsed.command) || parsed.command === "resume");
+      (isPublicCallableRole(parsed.command) ||
+        parsed.command === "resume" ||
+        parsed.command === "new");
     if (
       parsed.host !== undefined &&
       !parsed.help &&
@@ -1160,6 +1168,24 @@ export async function runAkRole(
       };
     }
 
+    // #724 explicit fresh summons: `ak-role new <role> …` — same role argv, always mint.
+    // Rewrites onto the role command with freshSummons; auto-resume and resume stay intact.
+    if (parsed.command === "new") {
+      const role = parsed.args[0];
+      if (role === undefined) {
+        throw new CliUsageError("usage: ak-role new <role> …");
+      }
+      if (!isPublicCallableRole(role)) {
+        throw new CliUsageError(`usage: ak-role new <role> …; unknown role: ${role}`);
+      }
+      parsed = {
+        ...parsed,
+        command: role,
+        args: parsed.args.slice(1),
+      };
+      env = { ...env, freshSummons: true };
+    }
+
     // Resume reopens an exact Role run (#416): caller decides; session principal
     // must still exist. Seat and dispatch follow the durable admitted role.
     // #471: unique parser owns {runId, message?}; five role paths only consume it.
@@ -1202,7 +1228,10 @@ export async function runAkRole(
       return cliResultFromRoleRun(result);
     }
 
-    if (isPublicCliSupportCommand(parsed.command)) {
+    if (
+      parsed.command !== undefined &&
+      isPublicCliSupportCommand(parsed.command)
+    ) {
       throw new CliUsageError(`unhandled support command: ${parsed.command}`);
     }
 

package/src/public-cli/countersign-run.ts

@@ -122,6 +122,7 @@ export async function runPublicCountersign(
       projectRoot,
       role: "countersign",
       ticketNumber: probedTicketNumber,
+      freshSummons: env.freshSummons,
       summons,
       resume: (runId, materials) =>
         runPublicCountersignResume(

package/src/public-cli/inspector-run.ts

@@ -109,6 +109,7 @@ export async function runPublicInspector(
       projectRoot,
       role: "inspector",
       ticketNumber: probedTicketNumber,
+      freshSummons: env.freshSummons,
       summons,
       resume: (runId, materials) =>
         runPublicInspectorResume(

package/src/public-cli/notary-run.ts

@@ -119,6 +119,7 @@ export async function runPublicNotary(
       projectRoot,
       role: "notary",
       ticketNumber,
+      freshSummons: env.freshSummons,
       summons,
       resume: (runId, materials) =>
         runPublicNotaryResume(

package/src/public-cli/option-definitions.ts

@@ -1271,6 +1271,17 @@ const SUPPORT_COMMAND_HELP = {
       "ak-role --engine agy resume 01abc…",
     ],
   },
+  new: {
+    command: "new",
+    summary:
+      "Explicit fresh summons: same role options as a direct call, but always mint a new run (skip same-ticket auto-resume). Caller chooses new vs resume; no overflow judgment.",
+    usage: ["ak-role new <role> [options] …"],
+    examples: [
+      'ak-role new countersign --attach ./ticket.md "裁：本票 #708 是否足以开工。"',
+      "ak-role new notary --source-run 01abc…@countersign",
+      "ak-role --host grok-build new inspector --attach ./change.patch",
+    ],
+  },
 } as const satisfies Record<string, PublicCommandHelpFacts>;
 
 /**

package/src/public-cli/post-admission.ts

@@ -110,6 +110,11 @@ export type PostAdmissionEnv = {
   sessionAppender: SessionCustomEntryAppender;
   autoResumeLimit?: number;
   createRunId?: () => string;
+  /**
+   * #724 explicit fresh summons (`ak-role new <role>`): skip same-ticket auto-resume
+   * and mint a new run. Absent on ordinary role commands and on `ak-role resume`.
+   */
+  freshSummons?: true;
 };
 
 /**
@@ -294,7 +299,6 @@ export async function dispatchPostAdmissionTurn<
           ? await projectHostTransitionPriorNative({
               previousHost,
               liveHost,
-              runDirectory: admitted.runDirectory,
               piSessionFile: principalCoordinates.sessionFile,
             })
           : undefined;

package/src/public-cli/registry.ts

@@ -27,6 +27,7 @@ export const PUBLIC_CLI_SUPPORT_COMMANDS = [
   "config",
   "help",
   "resume",
+  "new",
 ] as const;
 
 export type PublicCliSupportCommand = (typeof PUBLIC_CLI_SUPPORT_COMMANDS)[number];