@akagilnc/pi-workflow-roles 0.1.5015 → 0.1.5063

package/dist/public-cli/instruction-seat-run.js

@@ -8,17 +8,17 @@ import { resolve, sep } from "node:path";
 import { isSafePositiveTicketNumber, readBoardTicketNumber } from "../run-ticket-number.js";
 import { NotarySourceRunError, resolveNotarySourceRunLocator } from "../notary-source-run.js";
 import { engineSessionMaterialFromOptions, pickEngineAxis } from "../package-resources/engine-material.js";
-import { loadPackagedMethodSkillMaterial, } from "../package-resources/method-skill.js";
-import { packagedAdmitsCountersign, packagedBindsBoardTicket, packagedMethodLoadFailureCause, packagedRebindSourceOnResume, packagedRoleMetadata, } from "../packaged-role-registry.js";
+import { packagedAdmitsCountersign, packagedBindsBoardTicket, packagedRebindSourceOnResume, packagedRoleMetadata, } from "../packaged-role-registry.js";
 import { isAuditorSoulRole } from "../auditor-soul.js";
 import { CliUsageError } from "./cli-errors.js";
 import { admitPublicRole, bindAdmittedTicketNumber, bindCourtTicketNumbersOnAdmitted, buildInstructionTransportPrompt, materializeCountersignInvocation, persistAdmittedSourceRunPath, recordAdmittedCorrelation, recordChildDiaristRun, relocateAdmittedRunToTicket, withPreparedAttachments, } from "./invocation.js";
-import { presentControlledFailure, prepareSummonsResumeMaterials, resolveResumeMethodMaterialAdapters, roleTurnOptions, runPostAdmissionOneShot, runPostAdmissionResumable, runPostAdmissionSeatResume, resumeTurnRequestProjectionOptions, } from "./post-admission.js";
+import { presentControlledFailure, prepareSummonsResumeMaterials, roleTurnOptions, runPostAdmissionOneShot, runPostAdmissionResumable, runPostAdmissionSeatResume, resumeTurnRequestProjectionOptions, } from "./post-admission.js";
 import { buildAutoResumeContinuationPrompt, loadResumablePublicRole, markRunAdmitted, parentRunPathFromGatePointerInstruction, } from "./run-lifecycle.js";
 import { tryResumeSameTicketSeatRun } from "./seat-ticket-binding.js";
 import { presentStructuralRejection, seatKnownFailureResolver, trySettlePublicSeat, } from "./settlement.js";
+import { warnMissingMethodSkills } from "./machine-method-skills.js";
 import { formatTerminalResult, isLawfulTypedTerminalOutcome, } from "./terminal.js";
-import { admittedSeatTurnDetails, packagedSettleSkill, projectRoleTurnRequest, } from "./turn-request.js";
+import { admittedSeatTurnDetails, projectRoleTurnRequest, requiredMethodSkills, } from "./turn-request.js";
 import { invokeCourtDiarist, runCountersignCourtDiaristStation, } from "./countersign-run.js";
 function roleRecord(role) {
     const record = packagedRoleMetadata(role);
@@ -29,7 +29,7 @@ function roleRecord(role) {
 }
 /** Project any admitted public role onto the host-neutral turn request. */
 export function buildInstructionSeatTurnRequest(admitted, options) {
-    return projectRoleTurnRequest(admitted, admittedSeatTurnDetails(admitted, options.packageRoot), options);
+    return projectRoleTurnRequest(admitted, admittedSeatTurnDetails(admitted, options.home, options.host), options);
 }
 function initialPrompt(admitted, env) {
     const record = roleRecord(admitted.role);
@@ -58,11 +58,11 @@ async function bindAndRelocateDiarist(admitted, authority, lease) {
     }
     await relocateAdmittedRunToTicket(admitted, authority, lease);
 }
-function seatAdapters(admitted, env, material) {
+function seatAdapters(admitted, env) {
     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),
+        trySettle: (seat, authority, scope) => trySettlePublicSeat(seat, authority, scope),
         ...(present === "always" ? { shouldPresentSettled: () => true } : {}),
         ...(present === "typed"
             ? { shouldPresentSettled: (terminal) => isLawfulTypedTerminalOutcome(terminal.roleOutcome) }
@@ -126,24 +126,8 @@ async function withAuditorSoulEnv(options) {
 }
 async function dispatchAdmitted(admitted, env, io) {
     const record = roleRecord(admitted.role);
-    let material;
-    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);
-        }
-    }
-    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) => {
         const auto = "inCallAutoResume" in record && record.inCallAutoResume === true;
         if (auto) {
@@ -258,9 +242,7 @@ async function runCountersignBody(parsed, env, io) {
             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,
@@ -296,14 +278,16 @@ async function runCountersignBody(parsed, env, io) {
             let typedTicket;
             let typedCourtTicketNumbers;
             let identityDiaristRan = false;
-            let unboundDiaristRunId;
-            if (env.runCourtDiaristStation === undefined) {
+            let childDiaristRunId;
+            let pausedDiaristTerminal;
+            if (gateParentRunPath === undefined && env.runCourtDiaristStation === undefined) {
                 let outcome;
                 try {
                     outcome = await invokeCourtDiarist({
                         instruction: parsed.instruction ?? "",
                         projectRoot: admitted.projectRoot,
                         failureLabel: "unbound summons",
+                        correlationId: admitted.runId,
                         ...(env.boundTicketNumber === undefined ? {} : { boundTicketNumber: env.boundTicketNumber }),
                     }, env, io);
                 }
@@ -318,16 +302,16 @@ async function runCountersignBody(parsed, env, io) {
                     }, seatAdapters(admitted, env), env.principalAuthority, io);
                 }
                 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,
@@ -337,19 +321,19 @@ async function runCountersignBody(parsed, env, io) {
                     }, seatAdapters(admitted, env), env.principalAuthority, io);
                 }
                 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);
@@ -401,7 +385,11 @@ async function runCountersignBody(parsed, env, io) {
                         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));
@@ -486,7 +474,6 @@ export async function runPublicInstructionSeat(argv, env, io, role, parseArgv) {
                 projectRoot,
                 role,
                 parentRunPath: sourceDirectory,
-                ...(auditorTicket === undefined ? {} : { ticketNumber: auditorTicket }),
                 freshSummons: env.freshSummons,
                 summons,
                 resume: (runId, materials) => runPublicInstructionSeatResume({ runId, ...(materials === undefined ? {} : { summons: materials }) }, env, io),
@@ -511,7 +498,6 @@ export async function runPublicInstructionSeat(argv, env, io, role, parseArgv) {
                 projectRoot,
                 role,
                 parentRunPath,
-                ...(env.boundTicketNumber === undefined ? {} : { ticketNumber: env.boundTicketNumber }),
                 freshSummons: env.freshSummons,
                 summons,
                 resume: (runId, materials) => runPublicInstructionSeatResume({ runId, ...(materials === undefined ? {} : { summons: materials }) }, env, io),
@@ -537,7 +523,6 @@ export async function runPublicInstructionSeat(argv, env, io, role, parseArgv) {
             throw error;
         }
         const resumeInstruction = env.reviewReask ?? env.gateReviewInstruction;
-        const knownTicket = (await readBoardTicketNumber(source.runDirectory)) ?? env.boundTicketNumber;
         const summons = {
             sourceRunPath: source.runDirectory,
             sourceRun: source,
@@ -548,7 +533,6 @@ export async function runPublicInstructionSeat(argv, env, io, role, parseArgv) {
             projectRoot,
             role,
             parentRunPath: source.runDirectory,
-            ...(knownTicket === undefined ? {} : { ticketNumber: knownTicket }),
             freshSummons: env.freshSummons,
             summons,
             resume: (runId, materials) => runPublicInstructionSeatResume({ runId, ...(materials === undefined ? {} : { summons: materials }) }, env, io),
@@ -579,54 +563,34 @@ export async function runPublicInstructionSeat(argv, env, io, role, parseArgv) {
     }
     const runAdmitted = async () => {
         await markRunAdmitted(admitted, env.principalAuthority);
-        if (record.sameParent === "court-diarist") {
-            const { invokeCourtDiarist } = await import("./countersign-run.js");
-            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;
+            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);
+            }
             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);
             }
-            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);
-                }
+            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);
@@ -670,22 +634,26 @@ export async function runPublicInstructionSeatResume(request, env, io) {
         adapters: {
             trySettle: async () => undefined,
         },
-        afterAdmittedLoad: (admitted) => {
-            const skill = packagedSettleSkill(admitted);
-            if (skill === undefined) {
-                return Promise.resolve({ kind: "continue", 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", adapters: seatAdapters(admitted, env) };
         },
         ...(env.engine === undefined ? {} : { effectiveEngine: env.engine }),
     });
 }
+/** Continue the parent once any escalated child has submitted. */
+export async function continueParentAfterChild(parentRunId, child, env, io) {
+    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/dist/public-cli/invocation.js

@@ -9,7 +9,7 @@ import { tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { activationBookDirectory, ensureRealDirectoryTree, homeFromRunDirectory, pathContainedIn, resolveActivationLedgerHome, } from "../activation-ledger-topology.js";
 import { resolveBookKeyFromGit } from "../activation-ledger-git.js";
-import { ensureRoleRunDirectory, ensureRoleRunPlacement, roleRunArtifactsDirectory, roleRunPlacement, } from "../role-run-placement.js";
+import { ensureRoleRunDirectory, ensureRoleRunPlacement, listBookRunDirectories, roleRunArtifactsDirectory, roleRunPlacement, } from "../role-run-placement.js";
 import { packagedAdmittedSubject, packagedArgvResult, packagedBareToken, packagedBaseIsRevision, packagedEmitsAuthorityRefs, packagedPublicInstructionSubject, packagedRoleMetadata, packagedStoresSourceRunRaw, packagedSubjectChoices, } from "../packaged-role-registry.js";
 import { isSafePositiveTicketNumber, readBoardTicketNumber, requireSafePositiveTicketNumber, } from "../run-ticket-number.js";
 import { rewriteRunDirectoryPathFields, rewriteRunDirectoryPathValue, } from "../role-run-relocation.js";
@@ -164,15 +164,11 @@ export async function persistAdmittedSourceRunPath(admitted, sourceRunPath) {
 /**
  * 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, ticketNumber) {
-    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.ticketNumber = ticketNumber;
 }
@@ -229,7 +225,7 @@ export async function bindCourtTicketNumbersOnAdmitted(admitted, courtTicketNumb
     });
     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, authority, heldLease) {
     if (admitted.ticketNumber === undefined || !admitted.runDirectory.includes(`${sep}unbound${sep}runs${sep}`))
         return undefined;
@@ -252,6 +248,9 @@ export async function relocateAdmittedRunToTicket(admitted, authority, heldLease
             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 },
@@ -259,21 +258,18 @@ export async function relocateAdmittedRunToTicket(admitted, authority, heldLease
                 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));
             await rename(childDirectory, childTarget.runDirectory);
         }
     }
-    // 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);
     // rename moved the open lock inode with the directory. Transfer cleanup
@@ -312,24 +308,9 @@ export async function recordChildDiaristRun(parent, childRunId) {
 export async function bindTicketNumberOnRunDirectory(runDirectory, ticketNumber) {
     requireSafePositiveTicketNumber(ticketNumber, "bindTicketNumberOnRunDirectory");
     const admittedPath = join(runDirectory, "admitted-request.json");
-    const invocationPath = join(runDirectory, "invocation.json");
     const admitted = JSON.parse(await readFile(admittedPath, "utf8"));
-    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"));
-        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`, "utf8");
     await mergeInvocationIdentityPage(runDirectory, { ticketNumber });
 }

package/dist/public-cli/machine-method-skills.js

@@ -0,0 +1,150 @@
+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.js";
+import { packagedMethodSkillNames } from "../packaged-role-registry.js";
+/** Install source only. Which names are required comes from the role registry. */
+const SKILL_SOURCE = {
+    tdd: "mattpocock/skills",
+    "diagnosing-bugs": "mattpocock/skills",
+    "resolving-merge-conflicts": "mattpocock/skills",
+    "ak-cross-m-review": "Akagilnc/ak-cross-m-review",
+};
+function skillRoot(home) {
+    return join(home, ".agents/skills");
+}
+export function installedMethodSkillPath(home, name) {
+    return installedSkillPath(skillRoot(home), name);
+}
+function installedSkillPath(root, name) {
+    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.code;
+        if (code === "ENOENT" || code === "ENOTDIR" || code === "EACCES" || code === "EPERM" || code === "ELOOP")
+            return undefined;
+        throw error;
+    }
+}
+function linkedSkillRoot(home, host) {
+    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) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        return false;
+    }
+}
+function warnOccupied(path, stdout) {
+    stdout(`Warning: ${path} is already occupied; left untouched.\n`);
+}
+export async function warnMissingMethodSkills(home, host, role, skills, stdout) {
+    const missing = [];
+    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, home) {
+    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, skills, home) {
+    if (skills.length === 0)
+        return true;
+    return runSkillsCli([
+        "add", source,
+        ...skills.flatMap((skill) => ["--skill", skill]),
+        "--agent", "codex", "--global", "--yes",
+    ], home);
+}
+function updateRequiredSkills(home) {
+    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, stdout) {
+    const canonical = skillRoot(home);
+    const missingBySource = new Map();
+    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"]) {
+        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.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;
+}