@akagilnc/pi-workflow-roles 0.1.3758 → 0.1.3783

package/dist/host-descriptions.js

@@ -45,15 +45,56 @@ export const HOST_DESCRIPTIONS = Object.freeze({
         }),
     }),
 });
+/**
+ * Headless CLI family (#645). Claude is the first row; codex (#646) adds another.
+ * fixedArgs: print mode, isolation without `--bare` (OAuth stays), full permissions.
+ * `--setting-sources` empty = load no user/project/local CLAUDE.md/hooks/skills
+ * (role envelope is delivered via `--system-prompt` wholesale replace).
+ * `--strict-mcp-config` with no `--mcp-config` drops operator MCP + claude.ai connectors.
+ */
+export const HEADLESS_HOST_DESCRIPTIONS = Object.freeze({
+    "claude": Object.freeze({
+        binaryFromHome: Object.freeze([".local", "bin", "claude"]),
+        sessionBindingFile: "claude-headless-session.json",
+        fixedArgs: Object.freeze([
+            // One result envelope (not stream-json): typed receipt only; no event-stream copy.
+            "--output-format", "json",
+            "--permission-mode", "bypassPermissions",
+            // Empty sources: no user/project/local operator surface (envelope owns materials).
+            "--setting-sources", "",
+            // With adapter-supplied --mcp-config only (AK relay); drops operator + claude.ai MCP.
+            "--strict-mcp-config",
+        ]),
+        promptFlag: "-p",
+        modelFlag: "--model",
+        effortFlag: "--effort",
+        // File path keeps large role envelopes off ARG_MAX.
+        systemPromptFlag: "--system-prompt-file",
+        jsonSchemaFlag: "--json-schema",
+        mcpConfigFlag: "--mcp-config",
+        sessionIdFlag: "--session-id",
+        resumeFlag: "--resume",
+    }),
+});
 export function lookupHostDescription(host) {
     return Object.hasOwn(HOST_DESCRIPTIONS, host) ? HOST_DESCRIPTIONS[host] : undefined;
 }
+export function lookupHeadlessHostDescription(host) {
+    return Object.hasOwn(HEADLESS_HOST_DESCRIPTIONS, host) ? HEADLESS_HOST_DESCRIPTIONS[host] : undefined;
+}
+export function lookupHostFamily(host) {
+    if (lookupHostDescription(host) !== undefined)
+        return "acp";
+    if (lookupHeadlessHostDescription(host) !== undefined)
+        return "headless";
+    return undefined;
+}
 export function packagedExternalHostNames() {
-    return Object.keys(HOST_DESCRIPTIONS);
+    return [...Object.keys(HOST_DESCRIPTIONS), ...Object.keys(HEADLESS_HOST_DESCRIPTIONS)];
 }
-/** Legal persistent/invocation host: default pi, or a table key. */
+/** Legal persistent/invocation host: default pi, or a table key (any family). */
 export function assertRegisteredHostName(host) {
-    if (host === DEFAULT_ROLE_TURN_HOST || lookupHostDescription(host) !== undefined) {
+    if (host === DEFAULT_ROLE_TURN_HOST || lookupHostFamily(host) !== undefined) {
         return host;
     }
     throw new Error(`unregistered host: ${host}`);

package/dist/package-contracts/collector-output.js

@@ -25,10 +25,16 @@ function validateAcceptedCollectorReceipt(value) {
     materials: records(safeGet(group, "materials")),
     findings: records(safeGet(group, "findings"))
   }));
+  const unfinishedRaw = safeGet(value, "unfinishedReasons");
+  const unfinishedReasons = strings(unfinishedRaw);
+  const submissionProjection = projectSubmissionProjection(safeGet(value, "submissionProjection"));
+  const prStateRaw = safeGet(value, "prState");
+  const prState = typeof prStateRaw === "string" ? prStateRaw : void 0;
   return {
     host: safeGet(value, "host"),
     repository: safeGet(value, "repository"),
     prNumber: safeGet(value, "prNumber"),
+    ...prState === void 0 ? {} : { prState },
     manifestDigest: safeGet(value, "manifestDigest"),
     activationTime: safeGet(value, "activationTime"),
     deadlineTime: safeGet(value, "deadlineTime"),
@@ -36,6 +42,8 @@ function validateAcceptedCollectorReceipt(value) {
     finalSnapshotId: safeGet(value, "finalSnapshotId"),
     targetHead: safeGet(value, "targetHead"),
     groups,
+    ...unfinishedReasons.length > 0 ? { unfinishedReasons } : {},
+    ...submissionProjection === void 0 ? {} : { submissionProjection },
     requestAttempts: records(safeGet(value, "requestAttempts")),
     snapshots: records(safeGet(value, "snapshots")).map((snapshot) => ({
       snapshotId: safeGet(snapshot, "snapshotId"),
@@ -55,6 +63,30 @@ function validateAcceptedCollectorReceipt(value) {
     evidenceRecords: records(safeGet(value, "evidenceRecords")).map((record) => ({ evidenceId: safeGet(record, "evidenceId"), kind: safeGet(record, "kind"), versionId: safeGet(record, "versionId"), contentDigest: safeGet(record, "contentDigest"), firstObservedAt: safeGet(record, "firstObservedAt"), githubId: safeGet(record, "githubId"), authorLogin: safeGet(record, "authorLogin"), htmlUrl: safeGet(record, "htmlUrl"), authoritativeTime: safeGet(record, "authoritativeTime") }))
   };
 }
+function projectSubmissionProjection(raw) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return void 0;
+  const p = raw;
+  const out = {};
+  if (p["findingsSource"] === "absent" || p["findingsSource"] === "array" || p["findingsSource"] === "unreadable") {
+    out.findingsSource = p["findingsSource"];
+  }
+  if (typeof p["findingsProjectedCount"] === "number") {
+    out.findingsProjectedCount = p["findingsProjectedCount"];
+  }
+  if (typeof p["findingsUnprojected"] === "boolean") {
+    out.findingsUnprojected = p["findingsUnprojected"];
+  }
+  if (p["unfinishedReasonsSource"] === "absent" || p["unfinishedReasonsSource"] === "array" || p["unfinishedReasonsSource"] === "unreadable") {
+    out.unfinishedReasonsSource = p["unfinishedReasonsSource"];
+  }
+  if (typeof p["unfinishedReasonsProjectedCount"] === "number") {
+    out.unfinishedReasonsProjectedCount = p["unfinishedReasonsProjectedCount"];
+  }
+  if (typeof p["unfinishedReasonsUnprojected"] === "boolean") {
+    out.unfinishedReasonsUnprojected = p["unfinishedReasonsUnprojected"];
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
 export {
   COLLECTOR_ACCEPTED_TEXT,
   COLLECTOR_HOST,

package/dist/package-contracts/terminating-infrastructure.js

@@ -1,20 +1,21 @@
 import { Type } from "typebox";
 const INFRASTRUCTURE_FAILURE_DECLARATION_KEY = "infrastructureFailure";
 const INFRASTRUCTURE_FAILURE_DIAGNOSTIC_KEY = "diagnostic";
+const infrastructureFailureNested = Type.Object(
+  {
+    [INFRASTRUCTURE_FAILURE_DIAGNOSTIC_KEY]: Type.Unknown({
+      description: "\u975E\u7A7A\u57FA\u7840\u8BBE\u65BD\u5931\u8D25\u8BCA\u65AD\u5B57\u7B26\u4E32\u3002\u65E0\u5931\u8D25\u65F6\u5FC5\u987B\u7701\u7565\u6574\u4E2A infrastructureFailure\u3002\u5F62\u72B6\u6307\u5F15\uFF0C\u975E schema \u95F8\u3002"
+    })
+  },
+  {
+    additionalProperties: true,
+    description: "\u57FA\u7840\u8BBE\u65BD\u771F\u5B9E\u5931\u8D25\u58F0\u660E\uFF08\u5982\u9700\uFF09\u3002\u89C4\u8303\u5F62\uFF1A{ diagnostic: \u975E\u7A7A\u8BCA\u65AD\u5B57\u7B26\u4E32 }\uFF1B\u65E0\u5931\u8D25\u65F6\u5FC5\u987B\u7701\u7565\u3002\u5F62\u72B6\u6307\u5F15\uFF0C\u975E schema \u95F8\u3002"
+  }
+);
+infrastructureFailureNested.required = [];
 const infrastructureFailureDeclarationSchema = Type.Object(
   {
-    [INFRASTRUCTURE_FAILURE_DECLARATION_KEY]: Type.Object(
-      {
-        [INFRASTRUCTURE_FAILURE_DIAGNOSTIC_KEY]: Type.String({
-          minLength: 1,
-          description: "\u975E\u7A7A\u57FA\u7840\u8BBE\u65BD\u5931\u8D25\u8BCA\u65AD"
-        })
-      },
-      {
-        additionalProperties: true,
-        description: "\u57FA\u7840\u8BBE\u65BD\u5931\u8D25\u58F0\u660E"
-      }
-    )
+    [INFRASTRUCTURE_FAILURE_DECLARATION_KEY]: infrastructureFailureNested
   },
   { additionalProperties: true }
 );

package/dist/pi/role-turn-host.js

@@ -91,8 +91,7 @@ function buildActivationFlagArgs(activation) {
                 "collector",
                 "--ak-collector-repo",
                 activation.repo,
-                "--ak-collector-pr",
-                activation.pr,
+                ...(activation.pr === undefined ? [] : ["--ak-collector-pr", activation.pr]),
                 ...(activation.requestManifestPath === undefined
                     ? []
                     : ["--ak-collector-request-manifest", activation.requestManifestPath]),

package/dist/public-cli/github-remote.js

@@ -0,0 +1,45 @@
+/**
+ * Shared github.com remote URL → owner/repo parse (#676 B/D7).
+ * One authority for collector admission origin and upstream head owner.
+ */
+/** Parse owner from a github.com remote URL; undefined when not a GitHub owner/repo remote. */
+export function ownerFromGitHubRemoteUrl(remoteUrl) {
+    const ownerRepo = ownerRepoFromGitHubRemoteUrl(remoteUrl);
+    if (ownerRepo === undefined)
+        return undefined;
+    return ownerRepo.split("/")[0].toLowerCase();
+}
+/** Parse owner/repo identity from a github.com remote URL; undefined when not exact. */
+export function ownerRepoFromGitHubRemoteUrl(remoteUrl) {
+    const trimmed = remoteUrl.trim();
+    // git@github.com:owner/repo.git — exact owner/repo identity only.
+    const scp = /^git@github\.com:([^/\s]+)\/([^/\s]+?)(?:\.git)?$/i.exec(trimmed);
+    if (scp) {
+        return `${scp[1]}/${stripGitSuffix(scp[2])}`;
+    }
+    // ssh://git@github.com/owner/repo(.git) — exact owner/repo identity only.
+    const ssh = /^ssh:\/\/git@github\.com\/([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/i.exec(trimmed);
+    if (ssh) {
+        return `${ssh[1]}/${stripGitSuffix(ssh[2])}`;
+    }
+    // https://github.com/owner/repo(.git) and git://github.com/... — exact two-segment path.
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        return undefined;
+    }
+    if (!/^github\.com$/i.test(parsed.hostname))
+        return undefined;
+    // Non-identity URL material (query/hash/extra path) is not a repository remote.
+    if (parsed.search !== "" || parsed.hash !== "")
+        return undefined;
+    const parts = parsed.pathname.split("/").filter((p) => p.length > 0);
+    if (parts.length !== 2)
+        return undefined;
+    return `${parts[0]}/${stripGitSuffix(parts[1])}`;
+}
+function stripGitSuffix(name) {
+    return name.toLowerCase().endsWith(".git") ? name.slice(0, -4) : name;
+}

package/dist/public-cli/invocation.js

@@ -10,7 +10,9 @@ import { activationBookDirectory, ensureRealDirectoryTree, homeFromRunDirectory,
 import { resolveBookKeyFromGit } from "../activation-ledger-git.js";
 import { readRunTicketNumber } from "../run-ticket-number.js";
 import { loadDoctorCase, } from "../doctor-evidence.js";
-import { COLLECTOR_FIXED_KICKOFF, emptyCollectorManifest, loadCollectorManifest, parseCollectorPrNumber, parseCollectorRepository, } from "../collector-config.js";
+import { emptyCollectorManifest, loadCollectorManifest, parseCollectorPrNumber, parseCollectorRepository, } from "../collector-config.js";
+import { resolveCollectorTarget } from "../collector-target.js";
+import { ownerRepoFromGitHubRemoteUrl } from "./github-remote.js";
 import { FixerPacketValidationError, parseFixerPrerequisites, } from "../package-contracts/fixer-packet.js";
 import { createProductionMergerGitState } from "../merger-git-state.js";
 import { validateMergerInput, } from "../merger-contracts.js";
@@ -1020,10 +1022,11 @@ export function parseCollectorArgv(args) {
         }
         positional.push(token);
     }
-    // Unconditional required (e.g. --pr) from typed table via shared consumer (#342).
+    // Unconditional required from typed table via shared consumer (#342).
+    // #676 D1: --pr is optional; ambiguous targets reject at admission, not by guessing.
     options.assertRequired();
     return {
-        prNumber: prNumber,
+        ...(prNumber === undefined ? {} : { prNumber }),
         instruction: positional.join(" "),
         attachmentPaths,
         ...(project === undefined ? {} : { project }),
@@ -1034,6 +1037,7 @@ export function parseCollectorArgv(args) {
 /**
  * Resolve owner/repo from the project's `origin` remote (github.com only).
  * Supports https and SSH GitHub URL shapes; never scrapes instruction prose.
+ * Missing origin / non-github remote → usage. Git execution failure → true cause (exit 1).
  */
 export function resolveGitHubRemoteRepository(projectRoot) {
     let remoteUrl;
@@ -1045,7 +1049,13 @@ export function resolveGitHubRemoteRepository(projectRoot) {
         }).trim();
     }
     catch (error) {
-        throw new CliUsageError("collector requires a github.com origin remote or an explicit --repo owner/repo", { cause: error });
+        // git remote get-url exit 2 = no such remote; other failures keep true cause.
+        if (isGitRemoteMissing(error)) {
+            throw new CliUsageError("collector requires a github.com origin remote or an explicit --repo owner/repo", { cause: error });
+        }
+        throw new Error("collector git failed: cannot read origin remote URL", {
+            cause: error instanceof Error ? error : new Error(String(error)),
+        });
     }
     if (remoteUrl.length === 0) {
         throw new CliUsageError("collector requires a github.com origin remote or an explicit --repo owner/repo");
@@ -1062,55 +1072,34 @@ export function resolveGitHubRemoteRepository(projectRoot) {
         throw new CliUsageError(detail, { cause: error });
     }
 }
-function ownerRepoFromGitHubRemoteUrl(remoteUrl) {
-    const trimmed = remoteUrl.trim();
-    // git@github.com:owner/repo.git — exact owner/repo identity only.
-    const scp = /^git@github\.com:([^/\s]+)\/([^/\s]+?)(?:\.git)?$/i.exec(trimmed);
-    if (scp) {
-        return `${scp[1]}/${stripGitSuffix(scp[2])}`;
-    }
-    // ssh://git@github.com/owner/repo(.git) — exact owner/repo identity only.
-    const ssh = /^ssh:\/\/git@github\.com\/([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/i.exec(trimmed);
-    if (ssh) {
-        return `${ssh[1]}/${stripGitSuffix(ssh[2])}`;
-    }
-    // https://github.com/owner/repo(.git) and git://github.com/... — exact two-segment path.
-    let parsed;
-    try {
-        parsed = new URL(trimmed);
-    }
-    catch {
-        return undefined;
-    }
-    if (!/^github\.com$/i.test(parsed.hostname))
-        return undefined;
-    // Non-identity URL material (query/hash/extra path) is not a repository remote.
-    if (parsed.search !== "" || parsed.hash !== "")
-        return undefined;
-    const parts = parsed.pathname.split("/").filter((p) => p.length > 0);
-    if (parts.length !== 2)
-        return undefined;
-    return `${parts[0]}/${stripGitSuffix(parts[1])}`;
-}
-function stripGitSuffix(name) {
-    return name.toLowerCase().endsWith(".git") ? name.slice(0, -4) : name;
+/**
+ * git remote get-url: exit 2 = no such remote on common git (missing config).
+ * Other statuses keep true cause — do not broaden into usage (#676 B).
+ */
+function isGitRemoteMissing(error) {
+    if (typeof error !== "object" || error === null)
+        return false;
+    const status = error.status;
+    return status === 2;
 }
 /**
  * Admit a Collector Role run: assemble the retained leg manifest from typed
- * declarations, resolve repository identity, and place the session under #78.
- * Does not preflight PR/author existence against GitHub.
+ * declarations, resolve repository + PR target (#676 D1), and place the session under #78.
+ * Explicit PR is not preflighted for existence; context resolution uses online association.
  */
 export async function admitCollectorInvocation(options) {
     if (options.project !== undefined) {
         requireOptionPath("--project", options.project);
     }
-    let prNumber;
-    try {
-        prNumber = parseCollectorPrNumber(options.prNumber);
-    }
-    catch (error) {
-        const detail = error instanceof Error ? error.message : String(error);
-        throw new CliUsageError(detail, { cause: error });
+    let explicitPrNumber;
+    if (options.prNumber !== undefined) {
+        try {
+            explicitPrNumber = parseCollectorPrNumber(options.prNumber);
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            throw new CliUsageError(detail, { cause: error });
+        }
     }
     const projectRoot = resolve(options.project ?? options.cwd);
     let repository;
@@ -1149,14 +1138,23 @@ export async function admitCollectorInvocation(options) {
     const attachmentsDirectory = join(runDirectory, "attachments");
     ensureRealDirectoryTree(ledgerHome, sessionDirectory);
     ensureRealDirectoryTree(ledgerHome, attachmentsDirectory);
+    // #676 A: freeze task materials BEFORE target resolution so the role receives
+    // real instruction + attachments. Admission binds only explicit --pr or unique
+    // head/commit association — task-text scrape is not a target lock.
     const attachments = await freezeAttachments(options.attachmentPaths ?? [], attachmentsDirectory);
+    const instruction = options.instruction ?? "";
+    const instructionEmpty = instruction.trim() === "";
+    const target = await resolveCollectorTarget({
+        projectRoot,
+        repository,
+        ...(explicitPrNumber === undefined ? {} : { explicitPrNumber }),
+    });
+    const prNumber = target.kind === "bound" ? target.prNumber : undefined;
     let requestManifestPath;
     if (manifestCanonicalJson !== undefined) {
         requestManifestPath = join(runDirectory, "request-manifest.json");
         await writeFile(requestManifestPath, manifestCanonicalJson, "utf8");
     }
-    const instruction = options.instruction ?? "";
-    const instructionEmpty = instruction.trim() === "";
     const admitted = {
         role: "collector",
         runId,
@@ -1166,7 +1164,7 @@ export async function admitCollectorInvocation(options) {
         principal,
         instruction,
         instructionEmpty,
-        prNumber,
+        ...(prNumber === undefined ? {} : { prNumber }),
         repository: repository.canonical,
         repositoryDisplay: repository.display,
         ...(requestManifestPath === undefined ? {} : { requestManifestPath }),
@@ -1196,19 +1194,20 @@ export async function admitCollectorInvocation(options) {
         runDirectory,
         principal,
         admittedRequestPath,
-        prNumber,
+        ...(prNumber === undefined ? {} : { prNumber }),
         repository,
         ...(requestManifestPath === undefined ? {} : { requestManifestPath }),
         manifestDigest,
     };
 }
 /**
- * Collector always consumes the fixed packaged kickoff (one-shot observation).
- * Optional public instruction is retained only in the admitted request.
+ * #676 A: Collector consumes the real call task + frozen attachments so the role
+ * can identify issue/PR from materials via ak_collector_bind_target. Explicit --pr
+ * still wins at admission; unique head/commit association also binds. No fixed
+ * kickoff rewrite of the caller task; no mechanical task-text target lock.
  */
-export function buildCollectorTransportPrompt(_admitted, engineMaterial) {
-    // Exact historical fixed kickoff bytes (one-shot observation).
-    return appendEngineSessionMaterial([COLLECTOR_FIXED_KICKOFF], engineMaterial).join("\n");
+export function buildCollectorTransportPrompt(admitted, engineMaterial) {
+    return buildInstructionTransportPrompt(admitted, engineMaterial);
 }
 /** Positive Issue number grammar shared with Doctor case path identity. */
 const DOCTOR_ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/;

package/dist/public-cli/load-production-external-host.js

@@ -0,0 +1,19 @@
+/**
+ * Family-dispatch loader for packaged external RoleTurnHost factories (#645).
+ * ACP rows → production ACP host; headless rows → production headless host.
+ * Unregistered names fail closed before any import.
+ */
+import { lookupHostFamily } from "../host-descriptions.js";
+import { loadProductionAcpHostFactory } from "./load-production-acp-host.js";
+import { loadProductionHeadlessHostFactory } from "./load-production-headless-host.js";
+/** Resolve the production host factory for one registered external host key. */
+export async function loadProductionExternalHostFactory(packageRoot, host) {
+    const family = lookupHostFamily(host);
+    if (family === "acp") {
+        return loadProductionAcpHostFactory(packageRoot, host);
+    }
+    if (family === "headless") {
+        return loadProductionHeadlessHostFactory(packageRoot, host);
+    }
+    throw new Error(`unregistered host: ${host}`);
+}

package/dist/public-cli/load-production-headless-host.js

@@ -0,0 +1,36 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/**
+ * Deferred loader for the packaged generic headless RoleTurnHost factory (#645).
+ *
+ * Public ak-role bin must not statically value-import the production host (or its
+ * role-runtime edges). Specifier is runtime-constructed so esbuild leaves this
+ * import external (ADR 0052 discovery stays peer-free).
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { lookupHeadlessHostDescription } from "../host-descriptions.js";
+/**
+ * Resolve the production headless host factory for one registered headless host
+ * key without a static graph edge into the public CLI bundle.
+ */
+export async function loadProductionHeadlessHostFactory(packageRoot, host) {
+    const description = lookupHeadlessHostDescription(host);
+    if (description === undefined) {
+        throw new Error(`unregistered headless host: ${host}`);
+    }
+    const built = join(packageRoot, "dist/headless-host/production-host.js");
+    const source = join(packageRoot, "src/headless-host/production-host.ts");
+    const target = existsSync(built) ? built : source;
+    const href = pathToFileURL(target).href;
+    const mod = (await import(__rewriteRelativeImportExtension(href)));
+    const create = mod.createProductionHeadlessRoleTurnHost;
+    return (options) => create({ ...options, description });
+}