@akagilnc/pi-workflow-roles 0.1.5015 → 0.1.5063

package/src/public-cli/instruction-seat-run.ts

@@ -10,15 +10,10 @@ import type { DurablePrincipalAuthority, RoleTurnRequest } from "../host-contrac
 import { isSafePositiveTicketNumber, readBoardTicketNumber } from "../run-ticket-number.ts";
 import { NotarySourceRunError, resolveNotarySourceRunLocator } from "../notary-source-run.ts";
 import { engineSessionMaterialFromOptions, pickEngineAxis } from "../package-resources/engine-material.ts";
-import {
-  loadPackagedMethodSkillMaterial,
-  type PackagedMethodSkillMaterial,
-} from "../package-resources/method-skill.ts";
 import type { PackagedRole } from "../packaged-role-registry.ts";
 import {
   packagedAdmitsCountersign,
   packagedBindsBoardTicket,
-  packagedMethodLoadFailureCause,
   packagedRebindSourceOnResume,
   packagedRoleMetadata,
 } from "../packaged-role-registry.ts";
@@ -42,7 +37,6 @@ import {
 import {
   presentControlledFailure,
   prepareSummonsResumeMaterials,
-  resolveResumeMethodMaterialAdapters,
   roleTurnOptions,
   runPostAdmissionOneShot,
   runPostAdmissionResumable,
@@ -67,6 +61,7 @@ import {
   trySettlePublicSeat,
 } from "./settlement.ts";
 import type { CliIo } from "./cli-io.ts";
+import { warnMissingMethodSkills } from "./machine-method-skills.ts";
 import {
   formatTerminalResult,
   isLawfulTypedTerminalOutcome,
@@ -74,8 +69,8 @@ import {
 } from "./terminal.ts";
 import {
   admittedSeatTurnDetails,
-  packagedSettleSkill,
   projectRoleTurnRequest,
+  requiredMethodSkills,
   type RoleTurnRequestProjectionOptions,
 } from "./turn-request.ts";
 import {
@@ -110,7 +105,7 @@ export function buildInstructionSeatTurnRequest(
 ): RoleTurnRequest {
   return projectRoleTurnRequest(
     admitted,
-    admittedSeatTurnDetails(admitted, options.packageRoot),
+    admittedSeatTurnDetails(admitted, options.home, options.host),
     options,
   );
 }
@@ -160,13 +155,12 @@ async function bindAndRelocateDiarist(
 function seatAdapters(
   admitted: AdmittedRoleInvocation,
   env: InstructionSeatRunEnv,
-  material?: PackagedMethodSkillMaterial,
 ): PostAdmissionAdapters<AdmittedRoleInvocation> {
   const record = roleRecord(admitted.role);
   const present = "presentSettled" in record ? record.presentSettled : "default";
   return {
     trySettle: (seat, authority, scope) =>
-      trySettlePublicSeat(seat, authority, scope, material, env.packageRoot),
+      trySettlePublicSeat(seat, authority, scope),
     ...(present === "always" ? { shouldPresentSettled: () => true } : {}),
     ...(present === "typed"
       ? { shouldPresentSettled: (terminal: TerminalResult) => isLawfulTypedTerminalOutcome(terminal.roleOutcome) }
@@ -233,23 +227,8 @@ async function dispatchAdmitted(
   io: CliIo,
 ): Promise<SeatRunResult> {
   const record = roleRecord(admitted.role);
-  let material: PackagedMethodSkillMaterial | undefined;
-  const skill = packagedSettleSkill(admitted);
-  if (skill !== undefined) {
-    try {
-      material = await loadPackagedMethodSkillMaterial(env.packageRoot, skill);
-    } catch (error) {
-      const knownCause = packagedMethodLoadFailureCause(admitted.role);
-      return await presentControlledFailure(admitted, {
-        timedOut: false,
-        code: null,
-        stderr: "",
-        thrown: error,
-        ...(knownCause === undefined ? {} : { knownCause }),
-      }, seatAdapters(admitted, env), env.principalAuthority, io) as SeatRunResult;
-    }
-  }
-  const adapters = seatAdapters(admitted, env, material);
+  await warnMissingMethodSkills(env.home, env.host, admitted.role, requiredMethodSkills(admitted), io.stdout);
+  const adapters = seatAdapters(admitted, env);
   const execute = async (activeEnv: InstructionSeatRunEnv): Promise<SeatRunResult> => {
     const auto = "inCallAutoResume" in record && record.inCallAutoResume === true;
     if (auto) {
@@ -388,9 +367,7 @@ async function runCountersignBody(
       projectRoot: resolve(parsed.project ?? env.cwd),
       role: "countersign",
       parentRunPath: gateParentRunPath,
-      ...(env.boundTicketNumber === undefined
-        ? {}
-        : { ticketNumber: env.boundTicketNumber }),
+      ...(isSafePositiveTicketNumber(env.boundTicketNumber) ? { ticketNumber: env.boundTicketNumber } : {}),
       freshSummons: env.freshSummons,
       summons: {
         sourceRunPath: gateParentRunPath,
@@ -430,15 +407,17 @@ async function runCountersignBody(
       let typedTicket: number | undefined;
       let typedCourtTicketNumbers: readonly number[] | undefined;
       let identityDiaristRan = false;
-      let unboundDiaristRunId: string | undefined;
+      let childDiaristRunId: string | undefined;
+      let pausedDiaristTerminal: TerminalResult | undefined;
 
-      if (env.runCourtDiaristStation === undefined) {
+      if (gateParentRunPath === undefined && env.runCourtDiaristStation === undefined) {
         let outcome: Awaited<ReturnType<typeof invokeCourtDiarist>>;
         try {
           outcome = await invokeCourtDiarist({
             instruction: parsed.instruction ?? "",
             projectRoot: admitted.projectRoot,
             failureLabel: "unbound summons",
+            correlationId: admitted.runId,
             ...(env.boundTicketNumber === undefined ? {} : { boundTicketNumber: env.boundTicketNumber }),
           }, env, io);
         } catch (error) {
@@ -454,17 +433,16 @@ async function runCountersignBody(
           }, seatAdapters(admitted, env), env.principalAuthority, io) as SeatRunResult;
         }
         identityDiaristRan = true;
+        if (outcome.identity.kind === "escalate") pausedDiaristTerminal = outcome.terminal;
         if (outcome.admitted?.runDirectory.includes(`${sep}unbound${sep}runs${sep}`)) {
-          unboundDiaristRunId = outcome.admitted.runId;
+          childDiaristRunId = outcome.admitted.runId;
         }
-        if (outcome.identity.kind === "escalate" || outcome.failedWithoutEscalate !== undefined) {
-          const diagnostic = outcome.identity.kind === "escalate"
-            ? outcome.identity.diagnostic
-            : outcome.failedWithoutEscalate?.diagnostic ?? "";
+        if (outcome.failedWithoutEscalate !== undefined) {
+          const diagnostic = outcome.failedWithoutEscalate.diagnostic;
           await materializeAdmission(
             isSafePositiveTicketNumber(env.boundTicketNumber) ? env.boundTicketNumber : undefined,
           );
-          if (unboundDiaristRunId !== undefined) await recordChildDiaristRun(admitted, unboundDiaristRunId);
+          if (childDiaristRunId !== undefined) await recordChildDiaristRun(admitted, childDiaristRunId);
           await markRunAdmitted(admitted, env.principalAuthority);
           return await presentControlledFailure(admitted, {
             timedOut: false,
@@ -474,19 +452,20 @@ async function runCountersignBody(
           }, seatAdapters(admitted, env), env.principalAuthority, io) as SeatRunResult;
         }
         if (outcome.identity.kind === "ticket") {
-          typedTicket = isSafePositiveTicketNumber(env.boundTicketNumber)
-            ? env.boundTicketNumber
-            : outcome.identity.ticketNumber;
+          typedTicket = outcome.identity.ticketNumber;
           typedCourtTicketNumbers = outcome.identity.courtTicketNumbers;
-        } else if (isSafePositiveTicketNumber(env.boundTicketNumber)) {
-          typedTicket = env.boundTicketNumber;
         }
       }
 
       await materializeAdmission(typedTicket);
       await markRunAdmitted(admitted, env.principalAuthority);
-      if (unboundDiaristRunId !== undefined) {
-        await recordChildDiaristRun(admitted, unboundDiaristRunId);
+      if (childDiaristRunId !== undefined) {
+        await recordChildDiaristRun(admitted, childDiaristRunId);
+      }
+      if (pausedDiaristTerminal !== undefined) {
+        // The child already submitted its own pause; no parent turn exists yet.
+        io.stdout(formatTerminalResult(pausedDiaristTerminal));
+        return { exitCode: 0, admitted, terminal: pausedDiaristTerminal };
       }
       if (gateParentRunPath !== undefined) {
         await persistAdmittedSourceRunPath(admitted, gateParentRunPath);
@@ -540,7 +519,11 @@ async function runCountersignBody(
           beforeDispatch: async (admittedSeat, lease) => {
             if (!packagedAdmitsCountersign(admittedSeat.role)) return;
             if (!identityDiaristRan || typedTicket !== undefined) {
-              await runCountersignCourtDiaristStation(admittedSeat, env, io);
+              const refresh = await runCountersignCourtDiaristStation(admittedSeat, env, io);
+              if (refresh !== undefined) {
+                io.stdout(formatTerminalResult(refresh.terminal));
+                return refresh.terminal;
+              }
             }
             await relocateAdmittedRunToTicket(admittedSeat, env.principalAuthority, lease);
             Object.assign(turnRequest, buildInstructionSeatTurnRequest(admittedSeat, turnProjection));
@@ -628,7 +611,6 @@ export async function runPublicInstructionSeat(
         projectRoot,
         role,
         parentRunPath: sourceDirectory,
-        ...(auditorTicket === undefined ? {} : { ticketNumber: auditorTicket }),
         freshSummons: env.freshSummons,
         summons,
         resume: (runId, materials) => runPublicInstructionSeatResume(
@@ -657,7 +639,6 @@ export async function runPublicInstructionSeat(
         projectRoot,
         role,
         parentRunPath,
-        ...(env.boundTicketNumber === undefined ? {} : { ticketNumber: env.boundTicketNumber }),
         freshSummons: env.freshSummons,
         summons,
         resume: (runId, materials) => runPublicInstructionSeatResume(
@@ -686,7 +667,6 @@ export async function runPublicInstructionSeat(
       throw error;
     }
     const resumeInstruction = env.reviewReask ?? env.gateReviewInstruction;
-    const knownTicket = (await readBoardTicketNumber(source.runDirectory)) ?? env.boundTicketNumber;
     const summons: SameTicketSummonsMaterials = {
       sourceRunPath: source.runDirectory,
       sourceRun: source,
@@ -697,7 +677,6 @@ export async function runPublicInstructionSeat(
       projectRoot,
       role,
       parentRunPath: source.runDirectory,
-      ...(knownTicket === undefined ? {} : { ticketNumber: knownTicket }),
       freshSummons: env.freshSummons,
       summons,
       resume: (runId, materials) => runPublicInstructionSeatResume(
@@ -737,52 +716,33 @@ export async function runPublicInstructionSeat(
 
   const runAdmitted = async (): Promise<SeatRunResult> => {
     await markRunAdmitted(admitted, env.principalAuthority);
-    if (record.sameParent === "court-diarist") {
-      const { invokeCourtDiarist } = await import("./countersign-run.ts");
-      const outcome = await invokeCourtDiarist({
-        instruction: parsed.instruction ?? "",
-        projectRoot: admitted.projectRoot,
-        failureLabel: "secretariat unbound summons",
-        attachmentPaths: admitted.attachments.map((attachment) => attachment.frozenPath),
-        correlationId: admitted.runId,
-      }, {
-        cwd: env.cwd,
-        home: env.home,
-        agentDir: env.agentDir,
-        packageRoot: env.packageRoot,
-        ...(env.credentials === undefined ? {} : { credentials: env.credentials }),
-        ...(env.signal === undefined ? {} : { signal: env.signal }),
-        ...(env.hostAdapters === undefined ? {} : { hostAdapters: env.hostAdapters }),
-      }, io);
+    if (role === "secretariat") {
+      let outcome: Awaited<ReturnType<typeof invokeCourtDiarist>>;
+      try {
+        outcome = await invokeCourtDiarist({
+          instruction: parsed.instruction ?? "",
+          projectRoot: admitted.projectRoot,
+          failureLabel: "secretariat unbound summons",
+          attachmentPaths: admitted.attachments.map((attachment) => attachment.frozenPath),
+          correlationId: admitted.runId,
+        }, env, io);
+      } catch (error) {
+        return await presentControlledFailure(admitted, {
+          timedOut: false, code: null, stderr: "", thrown: error,
+        }, seatAdapters(admitted, env), env.principalAuthority, io) as SeatRunResult;
+      }
       if (outcome.admitted?.runDirectory.includes(`${sep}unbound${sep}runs${sep}`)) {
         await recordChildDiaristRun(admitted, outcome.admitted.runId);
       }
-      if (outcome.identity.kind === "escalate" || outcome.failedWithoutEscalate !== undefined) {
-        const diagnostic = outcome.identity.kind === "escalate"
-          ? outcome.identity.diagnostic
-          : outcome.failedWithoutEscalate?.diagnostic ?? "";
+      if (outcome.failedWithoutEscalate !== undefined) {
         return await presentControlledFailure(admitted, {
-          timedOut: false,
-          code: null,
-          stderr: "",
-          thrown: new Error(diagnostic),
+          timedOut: false, code: null, stderr: "",
+          thrown: new Error(outcome.failedWithoutEscalate.diagnostic),
         }, seatAdapters(admitted, env), env.principalAuthority, io) as SeatRunResult;
       }
-      if (outcome.identity.kind === "ticket") {
-        try {
-          if (outcome.admitted === undefined) throw new Error("court diarist ticket has no admitted run");
-          await bindAdmittedTicketNumber(outcome.admitted, outcome.identity.ticketNumber);
-          await relocateAdmittedRunToTicket(outcome.admitted, env.principalAuthority);
-          await bindAdmittedTicketNumber(admitted, outcome.identity.ticketNumber);
-          await relocateAdmittedRunToTicket(admitted, env.principalAuthority);
-        } catch (error) {
-          return await presentControlledFailure(admitted, {
-            timedOut: false,
-            code: null,
-            stderr: "",
-            thrown: error,
-          }, seatAdapters(admitted, env), env.principalAuthority, io) as SeatRunResult;
-        }
+      if (outcome.identity.kind === "escalate" && outcome.terminal !== undefined) {
+        io.stdout(formatTerminalResult(outcome.terminal));
+        return { exitCode: 0, admitted, terminal: outcome.terminal };
       }
     }
     return dispatchAdmitted(admitted, env, io);
@@ -837,22 +797,32 @@ export async function runPublicInstructionSeatResume(
     adapters: {
       trySettle: async () => undefined,
     },
-    afterAdmittedLoad: (admitted) => {
-      const skill = packagedSettleSkill(admitted);
-      if (skill === undefined) {
-        return Promise.resolve({ kind: "continue" as const, adapters: seatAdapters(admitted, env) });
-      }
-      const knownCause = packagedMethodLoadFailureCause(admitted.role);
-      return resolveResumeMethodMaterialAdapters({
-        admitted,
-        authority: env.principalAuthority,
-        io,
-        loadMaterial: () => loadPackagedMethodSkillMaterial(env.packageRoot, skill),
-        adaptersWith: (material) => seatAdapters(admitted, env, material),
-        emptyAdapters: seatAdapters(admitted, env),
-        ...(knownCause === undefined ? {} : { knownCause }),
-      });
+    afterAdmittedLoad: async (admitted) => {
+      await warnMissingMethodSkills(env.home, env.host, admitted.role, requiredMethodSkills(admitted), io.stdout);
+      return { kind: "continue" as const, adapters: seatAdapters(admitted, env) };
     },
     ...(env.engine === undefined ? {} : { effectiveEngine: env.engine }),
   });
 }
+
+/** Continue the parent once any escalated child has submitted. */
+export async function continueParentAfterChild(
+  parentRunId: string,
+  child: AdmittedRoleInvocation,
+  env: InstructionSeatRunEnv,
+  io: CliIo,
+): Promise<SeatRunResult> {
+  const loaded = await loadResumablePublicRole(env.home, parentRunId, env.principalAuthority, true);
+  if (loaded.run.state !== "admitted") {
+    return runPublicInstructionSeatResume({ runId: parentRunId }, env, io);
+  }
+  const admitted = loaded.admitted;
+  if (admitted.role === "countersign" && admitted.ticketNumber !== undefined) {
+    const refresh = await runCountersignCourtDiaristStation(admitted, env, io, child.ticketNumber);
+    if (refresh !== undefined) {
+      io.stdout(formatTerminalResult(refresh.terminal));
+      return { exitCode: 0, admitted, terminal: refresh.terminal };
+    }
+  }
+  return dispatchAdmitted(admitted, env, io);
+}

package/src/public-cli/invocation.ts

@@ -27,6 +27,7 @@ import { resolveBookKeyFromGit } from "../activation-ledger-git.ts";
 import {
   ensureRoleRunDirectory,
   ensureRoleRunPlacement,
+  listBookRunDirectories,
   roleRunArtifactsDirectory,
   roleRunPlacement,
   type RoleRunSubject,
@@ -539,19 +540,13 @@ export async function persistAdmittedSourceRunPath(
 /**
  * Bind a post-admission resolved ticketNumber onto the in-memory admitted
  * object and both durable pages (invocation.json + admitted-request.json).
- * Used by known-ticket reuse when admission was unbound (#635 / #709).
- * Never clears an existing binding.
+ * A later typed role receipt replaces an earlier assertion (#1025).
  */
 export async function bindAdmittedTicketNumber(
   admitted: AdmittedRoleInvocation,
   ticketNumber: number,
 ): Promise<void> {
-  if (admitted.ticketNumber !== undefined) {
-    if (admitted.ticketNumber === ticketNumber) return;
-    throw new Error(
-      `bindAdmittedTicketNumber refuses to replace existing ticket #${admitted.ticketNumber} with #${ticketNumber}`,
-    );
-  }
+  if (admitted.ticketNumber === ticketNumber) return;
   await bindTicketNumberOnRunDirectory(admitted.runDirectory, ticketNumber);
   (admitted as { ticketNumber?: number }).ticketNumber = ticketNumber;
 }
@@ -642,7 +637,7 @@ export async function bindCourtTicketNumbersOnAdmitted(
   admitted.courtTicketNumbers = frozen;
 }
 
-/** Move a settled first-entry run from unbound to its asserted ticket directory. */
+/** File a role run under its latest typed ticket identity. */
 export async function relocateAdmittedRunToTicket(
   admitted: AdmittedRoleInvocation,
   authority: DurablePrincipalAuthority,
@@ -668,6 +663,8 @@ export async function relocateAdmittedRunToTicket(
     for (const childRunId of Array.isArray(childRunIds) ? childRunIds : []) {
       if (typeof childRunId !== "string") continue;
       const childDirectory = join(dirname(oldRunDirectory), `${childRunId}@diarist`);
+      // A child that already filed under a ticket keeps its own assertion.
+      if (!existsSync(childDirectory)) continue;
       const childTarget = roleRunPlacement(ledgerHome, {
         bookKey: admitted.bookKey,
         subject: { ticketNumber: admitted.ticketNumber },
@@ -675,7 +672,6 @@ export async function relocateAdmittedRunToTicket(
         role: "diarist",
       });
       authority.seal(childTarget);
-      if (!existsSync(childDirectory) && existsSync(childTarget.runDirectory)) continue;
       await bindTicketNumberOnRunDirectory(childDirectory, admitted.ticketNumber);
       await rehomeUnboundTicketProvenance(childDirectory, admitted.ticketNumber, admitted.projectRoot, homeFromRunDirectory(oldRunDirectory));
       ensureRoleRunDirectory(ledgerHome, dirname(childTarget.runDirectory));
@@ -683,14 +679,13 @@ export async function relocateAdmittedRunToTicket(
     }
   }
 
-  // An identity diarist can file before its caller obtains a ticket. Both its
-  // own bind and the caller's later bind use this existing relocation seam.
+  // The first ticket assignment moves only an unbound diarist's own diary.
   if (admitted.role === "diarist") {
     await rehomeUnboundTicketProvenance(oldRunDirectory, admitted.ticketNumber, admitted.projectRoot, homeFromRunDirectory(oldRunDirectory));
   }
 
-  // Rename commits the run placement. Diary assignment above is an idempotent
-  // Sitian append, not part of an atomic transaction with this directory move.
+  // Rename commits the run placement. Diary assignment above is a Sitian append
+  // outside the atomic directory move.
   // Persisted paths are resolved from typed run identity on read.
   await rename(oldRunDirectory, target.runDirectory);
 
@@ -752,34 +747,11 @@ export async function bindTicketNumberOnRunDirectory(
     "bindTicketNumberOnRunDirectory",
   );
   const admittedPath = join(runDirectory, "admitted-request.json");
-  const invocationPath = join(runDirectory, "invocation.json");
   const admitted = JSON.parse(await readFile(admittedPath, "utf8")) as Record<
     string,
     unknown
   >;
-  const existing = admitted.ticketNumber;
-  if (typeof existing === "number") {
-    if (existing === ticketNumber) return;
-    throw new Error(
-      `bindTicketNumberOnRunDirectory refuses to replace existing ticket #${existing} with #${ticketNumber}`,
-    );
-  }
-  // Conflict guard before any write: crash window of bindAdmittedTicketNumber
-  // can leave invocation bound while admitted-request is still unbound — refuse
-  // silent rebind. Read-before-merge; never check the page just overwritten.
-  if (existsSync(invocationPath)) {
-    const invocation = JSON.parse(
-      await readFile(invocationPath, "utf8"),
-    ) as Record<string, unknown>;
-    if (
-      typeof invocation.ticketNumber === "number" &&
-      invocation.ticketNumber !== ticketNumber
-    ) {
-      throw new Error(
-        `bindTicketNumberOnRunDirectory refuses to replace invocation ticket #${invocation.ticketNumber} with #${ticketNumber}`,
-      );
-    }
-  }
+  if (admitted.ticketNumber === ticketNumber) return;
   await writeFile(
     admittedPath,
     `${JSON.stringify({ ...admitted, ticketNumber }, null, 2)}\n`,

package/src/public-cli/machine-method-skills.ts

@@ -0,0 +1,153 @@
+import { accessSync, constants, statSync } from "node:fs";
+import { lstat, mkdir, symlink } from "node:fs/promises";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { HEADLESS_HOST_DESCRIPTIONS, HOST_DESCRIPTIONS } from "../host-descriptions.ts";
+import { packagedMethodSkillNames } from "../packaged-role-registry.ts";
+
+/** Install source only. Which names are required comes from the role registry. */
+const SKILL_SOURCE: Readonly<Record<string, string>> = {
+  tdd: "mattpocock/skills",
+  "diagnosing-bugs": "mattpocock/skills",
+  "resolving-merge-conflicts": "mattpocock/skills",
+  "ak-cross-m-review": "Akagilnc/ak-cross-m-review",
+};
+
+function skillRoot(home: string): string {
+  return join(home, ".agents/skills");
+}
+
+export function installedMethodSkillPath(home: string, name: string): string | undefined {
+  return installedSkillPath(skillRoot(home), name);
+}
+
+function installedSkillPath(root: string, name: string): string | undefined {
+  const path = join(root, name, "SKILL.md");
+  try {
+    if (!statSync(path).isFile()) return undefined;
+    accessSync(path, constants.R_OK);
+    return path;
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT" || code === "ENOTDIR" || code === "EACCES" || code === "EPERM" || code === "ELOOP") return undefined;
+    throw error;
+  }
+}
+
+function linkedSkillRoot(home: string, host: string | undefined): string | undefined {
+  if (host === "claude" || host === "claude-code") {
+    return join(process.env.CLAUDE_CONFIG_DIR?.trim() || join(home, ".claude"), "skills");
+  }
+  if (host === "hermes") return join(home, ".hermes/skills");
+  return undefined;
+}
+
+async function occupied(path: string): Promise<boolean> {
+  try {
+    await lstat(path);
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    return false;
+  }
+}
+
+function warnOccupied(path: string, stdout: (text: string) => void): void {
+  stdout(`Warning: ${path} is already occupied; left untouched.\n`);
+}
+
+export async function warnMissingMethodSkills(
+  home: string,
+  host: string | undefined,
+  role: string,
+  skills: readonly string[],
+  stdout: (text: string) => void,
+): Promise<void> {
+  const missing: string[] = [];
+  const linkedRoot = linkedSkillRoot(home, host);
+  for (const skill of skills) {
+    if (installedMethodSkillPath(home, skill) === undefined ||
+      (linkedRoot !== undefined && installedSkillPath(linkedRoot, skill) === undefined)) missing.push(skill);
+  }
+  for (const skill of missing) {
+    stdout(`Warning: required machine Skill "${skill}" is missing for ${role}; its method guidance may be unavailable and reduce work quality. Run \`ak-role setup\` to install required Skills.\n`);
+  }
+}
+
+function runSkillsCli(args: readonly string[], home: string): boolean {
+  const result = spawnSync("npx", ["--yes", "skills", ...args], {
+    stdio: "inherit",
+    env: { ...process.env, HOME: home },
+  });
+  if (result.error !== undefined) throw result.error;
+  return result.status === 0;
+}
+
+function addSkills(source: string, skills: readonly string[], home: string): boolean {
+  if (skills.length === 0) return true;
+  return runSkillsCli([
+    "add", source,
+    ...skills.flatMap((skill) => ["--skill", skill]),
+    "--agent", "codex", "--global", "--yes",
+  ], home);
+}
+
+function updateRequiredSkills(home: string): boolean {
+  const names = packagedMethodSkillNames();
+  if (names.length === 0) return true;
+  return runSkillsCli(["update", "-g", "-y", ...names], home);
+}
+
+/** Explicit user-run setup; delegates acquisition/install to the ecosystem Skills CLI. */
+export async function runMachineSkillSetup(home: string, stdout: (text: string) => void): Promise<number> {
+  const canonical = skillRoot(home);
+  const missingBySource = new Map<string, string[]>();
+  let unsourced = false;
+  for (const name of packagedMethodSkillNames()) {
+    const path = join(canonical, name);
+    if (await occupied(path)) {
+      warnOccupied(path, stdout);
+      continue;
+    }
+    const source = SKILL_SOURCE[name];
+    if (source === undefined) {
+      unsourced = true;
+      stdout(`Warning: required machine Skill "${name}" has no install source; setup did not install it.\n`);
+      continue;
+    }
+    const missing = missingBySource.get(source) ?? [];
+    missing.push(name);
+    missingBySource.set(source, missing);
+  }
+  for (const [source, missing] of missingBySource) {
+    if (!addSkills(source, missing, home)) return 1;
+  }
+  if (unsourced) return 1;
+
+  for (const host of ["claude-code", "hermes"] as const) {
+    const root = linkedSkillRoot(home, host)!;
+    const binaryFromHome = host === "claude-code"
+      ? HEADLESS_HOST_DESCRIPTIONS.claude!.binaryFromHome
+      : HOST_DESCRIPTIONS.hermes!.binaryFromHome;
+    try {
+      accessSync(join(home, ...binaryFromHome), constants.X_OK);
+    } catch (error) {
+      if (["ENOENT", "ENOTDIR", "EACCES"].includes((error as NodeJS.ErrnoException).code ?? "")) continue;
+      throw error;
+    }
+    for (const name of packagedMethodSkillNames()) {
+      const target = join(canonical, name);
+      if (installedMethodSkillPath(home, name) === undefined) continue;
+      const link = join(root, name);
+      if (await occupied(link)) {
+        warnOccupied(link, stdout);
+        continue;
+      }
+      await mkdir(root, { recursive: true });
+      await symlink(target, link, "dir");
+    }
+  }
+  if (!updateRequiredSkills(home)) return 1;
+  stdout("Machine method Skills setup finished. Existing same-name Skills were left untouched.\n");
+  return 0;
+}

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

@@ -223,8 +223,9 @@ function withOnceSuccessfulBeforeDispatch<
     ...adapters,
     beforeDispatch: async (admitted, lease) => {
       if (succeeded) return;
-      await hook(admitted, lease);
+      const result = await hook(admitted, lease);
       succeeded = true;
+      return result;
     },
   };
 }
@@ -352,7 +353,8 @@ export type PostAdmissionAdapters<
     result: RoleTurnResult;
     sessionFile: string;
   }) => Promise<RoleTurnKnownFailure | undefined>;
-  beforeDispatch?: (admitted: A, lease?: RunWriterLease) => Promise<void> | void;
+  /** A child office may pause this run with its unchanged terminal before a host turn starts. */
+  beforeDispatch?: (admitted: A, lease?: RunWriterLease) => Promise<T | void> | T | void;
   /**
    * After the host turn settles and before any held writer lease is released.
    * Post-turn bind/relocate (e.g. Diarist first assert) must run here so a
@@ -709,9 +711,8 @@ export async function dispatchPostAdmissionTurn<
       };
     }
     try {
-      // #858: an unbound seat may assert its ticket on the existing receipt.
-      // Read the original accepted payload; do not rewrite it, infer from prose,
-      // or reject missing/malformed declarations. An existing binding wins.
+      // #858: the first typed assertion files an unbound run. Later receipts
+      // remain untouched; this seam does not adjudicate a ticket change.
       if (admitted.ticketNumber === undefined) {
         const rows = await readRecordedSubmissionRows(
           admitted.projectRoot,
@@ -825,7 +826,10 @@ export async function dispatchPostAdmissionTurn<
     // (#840 父子不层叠).
     if (adapters.beforeDispatch !== undefined) {
       try {
-        await adapters.beforeDispatch(admitted, lease);
+        const paused = await adapters.beforeDispatch(admitted, lease);
+        if (paused !== undefined) {
+          return { exitCode: 0, admitted, terminal: paused, skipAutoResume: true as const };
+        }
       } catch (error) {
         const settled = (await presentControlledFailure(
           admitted,
@@ -1363,6 +1367,7 @@ export function resumeTurnRequestProjectionOptions(
   return {
     packageRoot: env.packageRoot,
     home: env.home,
+    ...(env.host === undefined ? {} : { host: env.host }),
     agentDir: env.agentDir,
     ...(env.model === undefined ? {} : { model: env.model }),
     ...pickEngineAxis(env),
@@ -1389,6 +1394,7 @@ export function roleTurnOptions(
   return {
     packageRoot: env.packageRoot,
     home: env.home,
+    ...(env.host === undefined ? {} : { host: env.host }),
     agentDir: env.agentDir,
     ...(env.model === undefined ? {} : { model: env.model }),
     ...pickEngineAxis(env),

package/src/public-cli/registry.ts

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