@kontourai/flow-agents 3.9.0 → 3.10.0

package/build/src/continuation-driver.js

@@ -4,11 +4,19 @@ import { randomUUID } from "node:crypto";
 import * as path from "node:path";
 import { inspectBuilderFlowSession, syncBuilderFlowSession } from "./builder-flow-runtime.js";
 import { atomicWriteJson, ensureSafeDirectory } from "./lib/fs.js";
+export class ContinuationAdapterTimeoutError extends Error {
+    code = "CONTINUATION_ADAPTER_TIMEOUT";
+    constructor(timeoutMs) {
+        super(`continuation adapter timed out after ${timeoutMs}ms`);
+        this.name = "ContinuationAdapterTimeoutError";
+    }
+}
 export async function runContinuationDriver(input) {
     assertMaxTurns(input.maxTurns);
     const now = input.now ?? (() => new Date());
     const waitForBarrier = input.waitForBarrier ?? (async () => "pending");
     const authorizeTurn = input.authorizeTurn ?? (async () => { });
+    const issueTurnAuthority = input.issueTurnAuthority;
     const adapterCommandIdentity = input.adapterCommandIdentity ?? null;
     let snapshot = validateSnapshot(await input.runtime.inspect());
     let state = loadOrCreateState(input.store, snapshot, input.maxTurns, adapterCommandIdentity, now);
@@ -25,10 +33,10 @@ export async function runContinuationDriver(input) {
         const barrier = state.pending_barrier;
         const readiness = await waitForBarrier(barrier);
         if (readiness === "pending") {
-            state = saveState(input.store, state, { status: "waiting" }, now);
+            state = saveState(input.store, state, { status: "waiting", active_turn_step: null, active_turn_public_key_digest: null }, now);
             return { outcome: "waiting", turns_started: state.turns_started, snapshot, barrier };
         }
-        state = saveState(input.store, state, { status: "active", pending_barrier: null }, now);
+        state = saveState(input.store, state, { status: "active", active_turn_step: null, active_turn_public_key_digest: null, pending_barrier: null }, now);
         appendEvent(input.store, state, snapshot, "resumed", now, { barrier });
     }
     snapshot = validateSnapshot(await input.runtime.synchronize());
@@ -39,17 +47,25 @@ export async function runContinuationDriver(input) {
     if (initialOutcome === "failed")
         return finishFailed(input.store, state, snapshot, now);
     if (initialOutcome === "waiting") {
-        state = saveState(input.store, state, { status: "waiting" }, now);
+        state = saveState(input.store, state, { status: "waiting", active_turn_step: null, active_turn_public_key_digest: null }, now);
         return { outcome: "waiting", turns_started: state.turns_started, snapshot };
     }
     while (state.turns_started < input.maxTurns) {
         await authorizeTurn();
         const iteration = state.turns_started + 1;
-        state = saveState(input.store, state, { status: "active", turns_started: iteration }, now);
+        state = saveState(input.store, state, {
+            status: "active",
+            turns_started: iteration,
+            active_turn_step: snapshot.current_step,
+            active_turn_public_key_digest: null,
+        }, now);
         appendEvent(input.store, state, snapshot, "turn_started", now);
         let result;
+        let request;
+        let authority;
+        let terminalized = false;
         try {
-            result = validateTurnResult(await input.runtime.execute(Object.freeze({
+            request = Object.freeze({
                 schema_version: "1.0",
                 run_id: snapshot.run_id,
                 definition_id: snapshot.definition_id,
@@ -57,23 +73,61 @@ export async function runContinuationDriver(input) {
                 iteration,
                 max_turns: input.maxTurns,
                 next_action: snapshot.next_action ? structuredClone(snapshot.next_action) : null,
-            })));
+            });
+            authority = issueTurnAuthority ? await issueTurnAuthority(request) : undefined;
+            if (authority) {
+                state = saveState(input.store, state, { active_turn_public_key_digest: authority.publicKeyDigest }, now);
+            }
+            result = validateTurnResult(await input.runtime.execute(request, authority ? {
+                continuationTurnSecret: authority.turnSecret,
+                continuationRunId: authority.runId,
+            } : undefined));
         }
         catch (error) {
-            appendEvent(input.store, state, snapshot, "turn_failed", now, { summary: boundedErrorMessage(error) });
+            const summary = boundedErrorMessage(error);
+            appendEvent(input.store, state, snapshot, "turn_failed", now, { summary, failure_kind: error instanceof ContinuationAdapterTimeoutError ? "timeout" : "adapter_error" });
             snapshot = validateSnapshot(await input.runtime.synchronize());
             assertMissionIdentity(state, snapshot);
             const outcome = canonicalOutcome(snapshot);
-            if (outcome === "done")
+            if (outcome === "done") {
+                terminalized = true;
                 return finishDone(input.store, state, snapshot, now);
-            if (outcome === "failed")
+            }
+            if (outcome === "failed") {
+                terminalized = true;
                 return finishFailed(input.store, state, snapshot, now);
+            }
             if (outcome === "waiting") {
                 state = saveState(input.store, state, { status: "waiting" }, now);
                 return { outcome: "waiting", turns_started: state.turns_started, snapshot };
             }
             continue;
         }
+        finally {
+            let cleanupFailure;
+            try {
+                if (authority && !authority.cleanup())
+                    cleanupFailure = "continuation turn authority cleanup returned false";
+            }
+            catch (error) {
+                cleanupFailure = boundedErrorMessage(error);
+            }
+            finally {
+                if (!terminalized)
+                    state = saveState(input.store, state, {
+                        active_turn_step: null,
+                        active_turn_public_key_digest: null,
+                    }, now);
+                if (cleanupFailure) {
+                    try {
+                        appendEvent(input.store, state, snapshot, "authority_cleanup_failed", now, { summary: cleanupFailure });
+                    }
+                    catch {
+                        // Audit is best effort. A cleanup extension must not replace the adapter outcome.
+                    }
+                }
+            }
+        }
         appendEvent(input.store, state, snapshot, "turn_completed", now, { summary: result.summary });
         if (result.status === "wait") {
             state = saveState(input.store, state, { status: "waiting", pending_barrier: result.barrier }, now);
@@ -87,6 +141,9 @@ export async function runContinuationDriver(input) {
         }
         snapshot = validateSnapshot(await input.runtime.synchronize());
         assertMissionIdentity(state, snapshot);
+        if (snapshot.status === "active" && snapshot.current_step === request.current_step) {
+            appendEvent(input.store, state, snapshot, "gate_not_advanced", now, { summary: "adapter completed without canonical gate advancement" });
+        }
         const outcome = canonicalOutcome(snapshot);
         if (outcome === "done")
             return finishDone(input.store, state, snapshot, now);
@@ -97,7 +154,11 @@ export async function runContinuationDriver(input) {
             return { outcome: "waiting", turns_started: state.turns_started, snapshot };
         }
     }
-    state = saveState(input.store, state, { status: "budget_exhausted" }, now);
+    state = saveState(input.store, state, {
+        status: "budget_exhausted",
+        active_turn_step: null,
+        active_turn_public_key_digest: null,
+    }, now);
     appendEvent(input.store, state, snapshot, "budget_exhausted", now);
     return { outcome: "budget_exhausted", turns_started: state.turns_started, snapshot };
 }
@@ -115,6 +176,7 @@ export async function driveBuilderFlowSession(input) {
         store: createFileContinuationStore(sessionDir),
         ...(input.waitForBarrier ? { waitForBarrier: input.waitForBarrier } : {}),
         ...(input.authorizeTurn ? { authorizeTurn: input.authorizeTurn } : {}),
+        ...(input.issueTurnAuthority ? { issueTurnAuthority: input.issueTurnAuthority } : {}),
         ...(input.now ? { now: input.now } : {}),
     });
 }
@@ -125,10 +187,11 @@ export async function withContinuationDriverLock(sessionDirInput, body) {
     ensureSafeDirectory(sessionDir, locksDir);
     const token = randomUUID();
     const lockFile = path.join(locksDir, `${process.pid}-${token}.lock`);
-    const owner = { schema_version: "1.0", pid: process.pid, token, created_at: new Date().toISOString() };
+    const lease = { pid: process.pid, token, created_at: new Date().toISOString() };
+    const owner = { schema_version: "1.0", ...lease };
     acquireDriverLock(locksDir, lockFile, owner);
     try {
-        return await body();
+        return await body(lease);
     }
     finally {
         releaseDriverLock(lockFile, token);
@@ -274,6 +337,8 @@ function loadOrCreateState(store, snapshot, maxTurns, adapterCommandIdentity, no
         adapter_command_identity: adapterCommandIdentity,
         status: "active",
         turns_started: 0,
+        active_turn_step: null,
+        active_turn_public_key_digest: null,
         pending_barrier: null,
         updated_at: now().toISOString(),
     };
@@ -285,12 +350,22 @@ function canonicalOutcome(snapshot) {
     return snapshot.disposition;
 }
 function finishDone(store, state, snapshot, now) {
-    const done = saveState(store, state, { status: "done", pending_barrier: null }, now);
+    const done = saveState(store, state, {
+        status: "done",
+        active_turn_step: null,
+        active_turn_public_key_digest: null,
+        pending_barrier: null,
+    }, now);
     appendEvent(store, done, snapshot, "done", now);
     return { outcome: "done", turns_started: done.turns_started, snapshot };
 }
 function finishFailed(store, state, snapshot, now) {
-    const failed = saveState(store, state, { status: "failed", pending_barrier: null }, now);
+    const failed = saveState(store, state, {
+        status: "failed",
+        active_turn_step: null,
+        active_turn_public_key_digest: null,
+        pending_barrier: null,
+    }, now);
     return { outcome: "failed", turns_started: failed.turns_started, snapshot };
 }
 function saveState(store, current, patch, now) {
@@ -309,6 +384,7 @@ function appendEvent(store, state, snapshot, type, now, extra = {}) {
         at: now().toISOString(),
         ...(extra.barrier ? { barrier: extra.barrier } : {}),
         ...(extra.summary ? { summary: extra.summary } : {}),
+        ...(extra.failure_kind ? { failure_kind: extra.failure_kind } : {}),
     });
 }
 function validateSnapshot(value) {
@@ -364,6 +440,13 @@ function validateState(state) {
         throw new Error("continuation driver turns_started must be a non-negative integer");
     if (state.turns_started > state.max_turns)
         throw new Error("continuation driver turns_started cannot exceed max_turns");
+    if (state.active_turn_step !== undefined && state.active_turn_step !== null && (typeof state.active_turn_step !== "string" || state.active_turn_step.length === 0)) {
+        throw new Error("continuation driver active_turn_step must be a non-empty string or null");
+    }
+    if (state.active_turn_public_key_digest !== undefined && state.active_turn_public_key_digest !== null
+        && (typeof state.active_turn_public_key_digest !== "string" || !/^[a-f0-9]{64}$/.test(state.active_turn_public_key_digest))) {
+        throw new Error("continuation driver active_turn_public_key_digest must be a SHA-256 hex digest or null");
+    }
     if (!new Set(["active", "waiting", "done", "failed", "budget_exhausted"]).has(state.status))
         throw new Error("continuation driver state status is invalid");
     if (state.status === "budget_exhausted" && state.turns_started !== state.max_turns) {

package/build/src/index.d.ts

@@ -2,8 +2,8 @@ export { BUILDER_BUILD_FLOW_ID, BUILDER_BUILD_FLOW_RELATIVE_PATH, BuilderBuildRu
 export type { BuilderBuildRunResult, BuilderBuildRunIdentityMismatch, BuilderBuildTrustBundleEvidenceInput, EvaluateBuilderBuildRunInput, LoadBuilderBuildRunInput, StartBuilderBuildRunInput, } from "./builder-flow-run-adapter.js";
 export { archiveBuilderFlowSession, cancelBuilderFlowSession, pauseBuilderFlowSession, recoverBuilderFlowSession, releaseBuilderFlowAssignment, resumeBuilderFlowSession, startBuilderFlowSession, syncBuilderFlowSession, } from "./builder-flow-runtime.js";
 export type { BuilderFlowAgentLifecycleInput, BuilderFlowAuthorizedLifecycleInput, BuilderFlowSessionInput, BuilderFlowSessionResult } from "./builder-flow-runtime.js";
-export { createFileContinuationStore, driveBuilderFlowSession, runContinuationDriver, withContinuationDriverLock, } from "./continuation-driver.js";
-export type { ContinuationBarrier, ContinuationDriverEvent, ContinuationDriverOutcome, ContinuationDriverState, ContinuationRuntimePort, ContinuationSnapshot, ContinuationStateStore, ContinuationTurnRequest, ContinuationTurnResult, DriveBuilderFlowSessionInput, RunContinuationDriverInput, } from "./continuation-driver.js";
+export { ContinuationAdapterTimeoutError, createFileContinuationStore, driveBuilderFlowSession, runContinuationDriver, withContinuationDriverLock, } from "./continuation-driver.js";
+export type { ContinuationBarrier, ContinuationDriverEvent, ContinuationDriverLockLease, ContinuationDriverOutcome, ContinuationDriverState, ContinuationRuntimePort, ContinuationSnapshot, ContinuationStateStore, ContinuationTurnAuthority, ContinuationTurnContext, ContinuationTurnRequest, ContinuationTurnResult, DriveBuilderFlowSessionInput, RunContinuationDriverInput, } from "./continuation-driver.js";
 export { builderLifecycleAuthorizationPayload, loadBuilderLifecycleAuthorization } from "./builder-lifecycle-authority.js";
 export type { BuilderLifecycleAuthorization } from "./builder-lifecycle-authority.js";
 export { defaultArtifactRootForRead, defaultCodexHome, defaultTelemetryDirForRead, defaultTelemetryDirsForRead, durableFlowAgentsRoot, durableInstallRecordPath, DURABLE_FLOW_AGENTS_DIR, FLOW_AGENTS_RUNTIME_DIR, FLOW_AGENTS_RUNTIME_SUBDIR, firstExistingPath, flowAgentsArtifactRoot, KONTOURAI_DIR, legacyTelemetryDataDir, LEGACY_TELEMETRY_DIR, telemetryDataDir, } from "./lib/local-artifact-root.js";

package/build/src/index.js

@@ -15,7 +15,7 @@ import * as path from "node:path";
 import { loadJson as _loadJson, writeJson as _writeJson } from "./cli/workflow-sidecar.js";
 export { BUILDER_BUILD_FLOW_ID, BUILDER_BUILD_FLOW_RELATIVE_PATH, BuilderBuildRunInputError, BuilderBuildRunIdentityError, evaluateBuilderBuildRun, loadBuilderBuildRun, resolveBuilderBuildFlowDefinitionPath, startBuilderBuildRun, } from "./builder-flow-run-adapter.js";
 export { archiveBuilderFlowSession, cancelBuilderFlowSession, pauseBuilderFlowSession, recoverBuilderFlowSession, releaseBuilderFlowAssignment, resumeBuilderFlowSession, startBuilderFlowSession, syncBuilderFlowSession, } from "./builder-flow-runtime.js";
-export { createFileContinuationStore, driveBuilderFlowSession, runContinuationDriver, withContinuationDriverLock, } from "./continuation-driver.js";
+export { ContinuationAdapterTimeoutError, createFileContinuationStore, driveBuilderFlowSession, runContinuationDriver, withContinuationDriverLock, } from "./continuation-driver.js";
 // Pure serialization contract used by external lifecycle authorities when
 // signing requests. This does not load, create, or mutate a Flow run.
 export { builderLifecycleAuthorizationPayload, loadBuilderLifecycleAuthorization } from "./builder-lifecycle-authority.js";

package/build/src/tools/build-universal-bundles.js

@@ -293,13 +293,30 @@ function appendExportNote(body, note) {
 function generatedAgentsSummary(agents) {
     return agents.slice().sort((a, b) => a.name.localeCompare(b.name)).map((spec) => `- \`${spec.name}\` — ${String(spec.description ?? "").trim()}`).join("\n");
 }
-function exportRootAgentsMd(label, agents, taskDir) {
-    return `# Universal Agent Bundle (${label})\n\nThis bundle was generated from the canonical source in this repo. Treat the repo root as the source of truth and regenerate the bundle instead of editing exported agent files by hand.\n\n## Shared Conventions\n\n- \`skills/\`, \`context/\`, \`powers/\`, \`prompts/\`, \`scripts/\`, and \`evals/\` were copied from the canonical source.\n- Cross-session task artifacts should live under \`${taskDir}\`.\n- Kiro-only hook wiring was stripped from exported non-Kiro agents to keep the package portable.\n\n## Exported Agents\n\n${generatedAgentsSummary(agents)}\n`;
+const BUNDLE_CAPABILITIES = {
+    "base": { label: "Base", installHint: "bash install.sh /path/to/workspace", instructionPath: "AGENTS.md", taskDir: runtimeTaskDir },
+    "kiro": { label: "Kiro", installHint: "bash install.sh $HOME/.flow-agents", instructionPath: "AGENTS.md", taskDir: runtimeTaskDir },
+    "claude-code": { label: "Claude Code", installHint: "bash install.sh /path/to/workspace", instructionPath: "CLAUDE.md", taskDir: manifest.claude_code.task_dir },
+    "codex": { label: "Codex", installHint: "bash install.sh /path/to/workspace", taskDir: manifest.codex.task_dir },
+    "opencode": { label: "opencode", installHint: "bash install.sh /path/to/workspace", instructionPath: "AGENTS.md", taskDir: manifest.opencode.task_dir },
+    "pi": { label: "pi", installHint: "bash install.sh /path/to/workspace", instructionPath: "AGENTS.md", taskDir: manifest.pi.task_dir },
+};
+function renderOperationalInstructions(capability) {
+    return `# Flow Agents\n\nUse the installed Flow Agents skills and runtime integrations for delivery work. Keep cross-session task artifacts under \`${capability.taskDir}\`.\n`;
 }
 const CODEX_LIVE_HOOKS_README = `\n## Running with hooks active (live)\n\n\`install.sh\` lays the bundle into a workspace, but a live Codex session needs a \`CODEX_HOME\` that has both the bundle's hooks/scripts AND your real credentials. Use the dedicated installer, which defaults to \`CODEX_HOME\` when set and otherwise \`~/.codex\`, flattens the config to the home root, and copies your auth from \`~/.codex\` when installing elsewhere:\n\n\`\`\`bash\nbash scripts/install-codex-home.sh\ncodex exec --dangerously-bypass-hook-trust -C /path/to/project \"<prompt>\"\n\`\`\`\n\nPass a positional destination to install into an explicit alternate Codex home.\n\nThe goal-fit Stop hook then enforces by default (\`FLOW_AGENTS_GOAL_FIT_MODE=block\`); set it to \`warn\` or \`off\` to override.\n`;
 function exportTargetReadme(label, installHint, extra = "") {
     return `# ${label} Bundle\n\nGenerated from the canonical source in this repository.\n\n## Install\n\n\`\`\`bash\n${installHint}\n\`\`\`\n\nThe install ships the full standalone base (skills, agents, powers) plus the\nFlow Kits. Kit depth is activated through the Kit Catalog, not at install time.\n\n## Contents\n\n- Harness-specific agents\n- Shared skills\n- Shared context, powers, prompts, scripts, and evals\n${extra}`;
 }
+function renderBundleReadme(capability, agents, extra = "") {
+    const inventory = `\n## Exported agents\n\nThe following agent definitions were generated from the canonical agent specifications in this repository. This inventory is documentation, not agent instructions.\n\n${generatedAgentsSummary(agents)}\n`;
+    return exportTargetReadme(capability.label, capability.installHint, `${inventory}${extra}`);
+}
+function writeBundlePolicy(bundle, capability, agents, readmeExtra = "") {
+    writeText(path.join(bundle, "README.md"), renderBundleReadme(capability, agents, readmeExtra));
+    if (capability.instructionPath)
+        writeText(path.join(bundle, capability.instructionPath), renderOperationalInstructions(capability));
+}
 function mapClaudeTools(allowedTools) {
     const ordered = [];
     for (const tool of Array.isArray(allowedTools) ? allowedTools : []) {
@@ -451,48 +468,59 @@ function copySharedContent(targetRoot, targetName, token) {
     }
     for (const dir of manifest.optional_copy_dirs ?? [])
         copyTree(path.join(root, dir), path.join(targetRoot, dir), targetName, token);
-    writeText(path.join(targetRoot, "build/package.json"), `${JSON.stringify({ type: "module" }, null, 2)}\n`);
+    writeText(path.join(targetRoot, "build/package.json"), `${JSON.stringify({
+        name: "@kontourai/flow-agents",
+        version: pkgVersion,
+        type: "module",
+    }, null, 2)}\n`);
     const commonBuilt = path.join(root, "build/src/tools/common.js");
     if (fs.existsSync(commonBuilt))
         writeText(path.join(targetRoot, "scripts/common.mjs"), readText(commonBuilt));
     copyTree(path.join(root, "build/src"), path.join(targetRoot, "build/src"), targetName, token);
 }
-function installScript(label, defaultDestDisplay, token, destFallbackShell, mergeConfig, stampConfig) {
-    const replaceBlock = token ? `\nexport DEST\nfind "$DEST" -type f \\( -name '*.json' -o -name '*.md' -o -name '*.sh' -o -name '*.js' -o -name '*.ts' -o -name '*.yaml' -o -name '*.yml' \\) -print0 | xargs -0 perl -0pi -e 's#${token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}#$ENV{DEST}#g'` : "";
+function installScript(label, capability, defaultDestDisplay, token, destFallbackShell, mergeConfig, stampConfig) {
+    const replaceBlock = token ? `\nexport DEST\nfind "$DEST" \\( -path "$DEST/AGENTS.md" -o -path "$DEST/CLAUDE.md" \\) -prune -o -type f \\( -name '*.json' -o -name '*.md' -o -name '*.sh' -o -name '*.js' -o -name '*.ts' -o -name '*.yaml' -o -name '*.yml' \\) -print0 | xargs -0 perl -0pi -e 's#${token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}#$ENV{DEST}#g'` : "";
     const destFallback = destFallbackShell ? `\nif [[ -z "$DEST" ]]; then\n  DEST="${destFallbackShell}"\nfi` : "";
     const destRequired = !destFallbackShell;
-    const requiredCheck = destRequired ? `if [[ -z "$DEST" ]]; then\n  usage\n  exit 2\nfi\n` : "";
+    const requiredCheck = `${destRequired ? `if [[ -z "$DEST" ]]; then\n  usage\n  exit 2\nfi\n` : ""}while [[ "$DEST" != "/" && "$DEST" == */ ]]; do\n  DEST="\${DEST%/}"\ndone\n`;
     const usageDest = destRequired ? "/path/to/workspace" : defaultDestDisplay;
     const mergeBlock = mergeConfig
         ? `\nif command -v node >/dev/null 2>&1; then\n  node "$DEST/scripts/install-merge.js" --config "$DEST/${mergeConfig.configRelPath}" --managed-hooks "$SRC/${mergeConfig.managedConfigRelPath}" --version "${mergeConfig.version}" --install-record "$DEST/${durableInstallRecordRel}" --runtime "${mergeConfig.runtime}" || true\nfi`
         : stampConfig
             ? `\nif command -v node >/dev/null 2>&1; then\n  node "$DEST/scripts/install-merge.js" --stamp-only --version "${stampConfig.version}" --install-record "$DEST/${durableInstallRecordRel}" --runtime "${stampConfig.runtime}" || true\nfi`
             : "";
-    return `#!/usr/bin/env bash\nset -euo pipefail\n\nusage() {\n  cat >&2 <<'EOF'\nusage: bash install.sh ${usageDest} [options]\n\nOptions:\n  --telemetry-sink NAME   local-files, local-kontour-console,\n                          kontour-hosted-console, user-hosted-console,\n                          or legacy aliases. May be repeated.\n  --console-url URL       Persist Console telemetry base URL.\n  --console-endpoint URL  Persist full Console telemetry records endpoint URL.\n  --console-token-file PATH\n                          Read Console telemetry bearer token from a file.\n  --console-tenant ID     Persist Console tenant identifier.\nEOF\n}\n\nDEST=""\nDEST_SET=0\nCONSOLE_CONFIG_ARGS=()\nwhile [[ $# -gt 0 ]]; do\n  case "$1" in\n    --telemetry-sink|--telemetry-sinks|--console-url|--console-endpoint|--console-endpoint-url|--console-token-file|--console-tenant|--console-tenant-id)\n      [[ $# -ge 2 ]] || { echo "install.sh: $1 requires a value" >&2; exit 2; }\n      CONSOLE_CONFIG_ARGS+=("$1" "$2")\n      shift 2\n      ;;\n    --help|-h)\n      usage\n      exit 0\n      ;;\n    -*)\n      echo "install.sh: unknown option: $1" >&2\n      usage\n      exit 2\n      ;;\n    *)\n      if [[ "$DEST_SET" -eq 1 ]]; then\n        echo "install.sh: unexpected argument: $1" >&2\n        usage\n        exit 2\n      fi\n      DEST="$1"\n      DEST_SET=1\n      shift\n      ;;\n  esac\ndone${destFallback}\n${requiredCheck}SRC="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"\n\nmkdir -p "$DEST"\nrsync -a ${token ? "--delete " : ""}${mergeConfig ? `--exclude="${mergeConfig.configRelPath}" ` : ""}"$SRC"/ "$DEST"/${replaceBlock}${mergeBlock}\nif [[ \${#CONSOLE_CONFIG_ARGS[@]} -gt 0 || -n "\${FLOW_AGENTS_TELEMETRY_SINK:-}" || -n "\${FLOW_AGENTS_TELEMETRY_SINKS:-}" || -n "\${FLOW_AGENTS_CONSOLE_URL:-}" || -n "\${CONSOLE_TELEMETRY_URL:-}" || -n "\${CONSOLE_URL:-}" || -n "\${FLOW_AGENTS_CONSOLE_TOKEN_FILE:-}" || -n "\${CONSOLE_TELEMETRY_TOKEN_FILE:-}" ]]; then\n  bash "$DEST/scripts/telemetry/install-console-config.sh" "$DEST/scripts/telemetry/telemetry.conf" "\${CONSOLE_CONFIG_ARGS[@]}"\nfi\necho "Installed ${label} bundle ${token ? "to" : "into"} $DEST"\n`;
+    // Excluding both discovery filenames protects any existing filesystem
+    // object, including during Kiro's --delete sync. Required guidance is then
+    // published with a no-overwrite hard link from a destination-local temp file.
+    const instructionBlock = capability.instructionPath
+        ? `\nif [[ ! -e "$DEST/${capability.instructionPath}" && ! -L "$DEST/${capability.instructionPath}" ]]; then\n  instruction_tmp="$(mktemp "$DEST/.flow-agents-instructions.XXXXXX")"\n  cp "$SRC/${capability.instructionPath}" "$instruction_tmp"\n  if ! ln "$instruction_tmp" "$DEST/${capability.instructionPath}" 2>/dev/null; then\n    if [[ ! -e "$DEST/${capability.instructionPath}" && ! -L "$DEST/${capability.instructionPath}" ]]; then\n      rm -f "$instruction_tmp"\n      echo "install.sh: could not safely install ${capability.instructionPath}" >&2\n      exit 1\n    fi\n  fi\n  rm -f "$instruction_tmp"\nfi`
+        : "";
+    return `#!/usr/bin/env bash\nset -euo pipefail\n\nusage() {\n  cat >&2 <<'EOF'\nusage: bash install.sh ${usageDest} [options]\n\nOptions:\n  --telemetry-sink NAME   local-files, local-kontour-console,\n                          kontour-hosted-console, user-hosted-console,\n                          or legacy aliases. May be repeated.\n  --console-url URL       Persist Console telemetry base URL.\n  --console-endpoint URL  Persist full Console telemetry records endpoint URL.\n  --console-token-file PATH\n                          Read Console telemetry bearer token from a file.\n  --console-tenant ID     Persist Console tenant identifier.\nEOF\n}\n\nDEST=""\nDEST_SET=0\nCONSOLE_CONFIG_ARGS=()\nwhile [[ $# -gt 0 ]]; do\n  case "$1" in\n    --telemetry-sink|--telemetry-sinks|--console-url|--console-endpoint|--console-endpoint-url|--console-token-file|--console-tenant|--console-tenant-id)\n      [[ $# -ge 2 ]] || { echo "install.sh: $1 requires a value" >&2; exit 2; }\n      CONSOLE_CONFIG_ARGS+=("$1" "$2")\n      shift 2\n      ;;\n    --help|-h)\n      usage\n      exit 0\n      ;;\n    -*)\n      echo "install.sh: unknown option: $1" >&2\n      usage\n      exit 2\n      ;;\n    *)\n      if [[ "$DEST_SET" -eq 1 ]]; then\n        echo "install.sh: unexpected argument: $1" >&2\n        usage\n        exit 2\n      fi\n      DEST="$1"\n      DEST_SET=1\n      shift\n      ;;\n  esac\ndone${destFallback}\n${requiredCheck}SRC="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"\n\nmkdir -p "$DEST"\nrsync -a ${token ? "--delete " : ""}--exclude='/AGENTS.md' --exclude='/CLAUDE.md' ${mergeConfig ? `--exclude="${mergeConfig.configRelPath}" ` : ""}"$SRC"/ "$DEST"/${instructionBlock}${replaceBlock}${mergeBlock}\nif [[ \${#CONSOLE_CONFIG_ARGS[@]} -gt 0 || -n "\${FLOW_AGENTS_TELEMETRY_SINK:-}" || -n "\${FLOW_AGENTS_TELEMETRY_SINKS:-}" || -n "\${FLOW_AGENTS_CONSOLE_URL:-}" || -n "\${CONSOLE_TELEMETRY_URL:-}" || -n "\${CONSOLE_URL:-}" || -n "\${FLOW_AGENTS_CONSOLE_TOKEN_FILE:-}" || -n "\${CONSOLE_TELEMETRY_TOKEN_FILE:-}" ]]; then\n  bash "$DEST/scripts/telemetry/install-console-config.sh" "$DEST/scripts/telemetry/telemetry.conf" "\${CONSOLE_CONFIG_ARGS[@]}"\nfi\necho "Installed ${label} bundle ${token ? "to" : "into"} $DEST"\n`;
 }
 function buildBase(agents) {
+    const capability = BUNDLE_CAPABILITIES["base"];
     const bundle = path.join(dist, "base");
     resetDir(bundle);
     copySharedContent(bundle, "base", "<bundle-root>");
     writeText(path.join(bundle, runtimeTaskDir, ".gitkeep"), "");
-    writeText(path.join(bundle, "AGENTS.md"), exportRootAgentsMd("Base", agents, runtimeTaskDir));
-    writeText(path.join(bundle, "README.md"), exportTargetReadme("Base", "bash install.sh /path/to/workspace"));
-    writeText(path.join(bundle, "install.sh"), installScript("Base", "/path/to/workspace", undefined, undefined, undefined, { runtime: "base", version: pkgVersion }));
+    writeBundlePolicy(bundle, capability, agents);
+    writeText(path.join(bundle, "install.sh"), installScript("Base", capability, "/path/to/workspace", undefined, undefined, undefined, { runtime: "base", version: pkgVersion }));
     fs.chmodSync(path.join(bundle, "install.sh"), 0o755);
 }
 function buildKiro(agents) {
+    const capability = BUNDLE_CAPABILITIES["kiro"];
     const bundle = path.join(dist, "kiro");
     const token = manifest.kiro.path_token;
     resetDir(bundle);
     copySharedContent(bundle, "kiro", token);
     for (const spec of agents)
         writeText(path.join(bundle, "agents", `${spec.name}.json`), sanitizeText(`${JSON.stringify(sanitizeAgentJson(spec), null, 2)}\n`, "kiro", token));
-    writeText(path.join(bundle, "AGENTS.md"), exportRootAgentsMd("Kiro", agents, runtimeTaskDir));
-    writeText(path.join(bundle, "README.md"), exportTargetReadme("Kiro", "bash install.sh $HOME/.flow-agents"));
-    writeText(path.join(bundle, "install.sh"), installScript("Kiro", "$HOME/.flow-agents", token, '${FLOW_AGENTS_DEST:-$HOME/.flow-agents}', undefined, { runtime: "kiro", version: pkgVersion }));
+    writeBundlePolicy(bundle, capability, agents);
+    writeText(path.join(bundle, "install.sh"), installScript("Kiro", capability, "$HOME/.flow-agents", token, '${FLOW_AGENTS_DEST:-$HOME/.flow-agents}', undefined, { runtime: "kiro", version: pkgVersion }));
     fs.chmodSync(path.join(bundle, "install.sh"), 0o755);
 }
 function buildClaudeCode(agents) {
+    const capability = BUNDLE_CAPABILITIES["claude-code"];
     const bundle = path.join(dist, "claude-code");
     resetDir(bundle);
     copySharedContent(bundle, "claude-code", "<bundle-root>");
@@ -503,12 +531,12 @@ function buildClaudeCode(agents) {
         writeText(path.join(bundle, ".claude/skills", name, "SKILL.md"), sanitizeText(readText(src), "claude-code", "<bundle-root>"));
     }
     writeText(path.join(bundle, ".claude/settings.json"), exportClaudeSettings());
-    writeText(path.join(bundle, "AGENTS.md"), exportRootAgentsMd("Claude Code", agents, manifest.claude_code.task_dir));
-    writeText(path.join(bundle, "README.md"), exportTargetReadme("Claude Code", "bash install.sh /path/to/workspace"));
-    writeText(path.join(bundle, "install.sh"), installScript("Claude Code", "/path/to/workspace", undefined, undefined, { configRelPath: ".claude/settings.json", managedConfigRelPath: ".claude/settings.json", runtime: "claude-code", version: pkgVersion }));
+    writeBundlePolicy(bundle, capability, agents);
+    writeText(path.join(bundle, "install.sh"), installScript("Claude Code", capability, "/path/to/workspace", undefined, undefined, { configRelPath: ".claude/settings.json", managedConfigRelPath: ".claude/settings.json", runtime: "claude-code", version: pkgVersion }));
     fs.chmodSync(path.join(bundle, "install.sh"), 0o755);
 }
 function buildCodex(agents) {
+    const capability = BUNDLE_CAPABILITIES["codex"];
     const bundle = path.join(dist, "codex");
     const excluded = new Set(manifest.codex.excluded_agents ?? []);
     const targetAgents = agents.filter((spec) => !excluded.has(spec.name));
@@ -526,9 +554,8 @@ function buildCodex(agents) {
     for (const { name, src } of collectAllSkills())
         exportSkillPackage(src, path.join(skillsRoot, name), "codex");
     validateExportedSkillPackages(skillsRoot);
-    writeText(path.join(bundle, "AGENTS.md"), exportRootAgentsMd("Codex", targetAgents, manifest.codex.task_dir));
-    writeText(path.join(bundle, "README.md"), exportTargetReadme("Codex", "bash install.sh /path/to/workspace", CODEX_LIVE_HOOKS_README));
-    writeText(path.join(bundle, "install.sh"), installScript("Codex", "/path/to/workspace", undefined, undefined, { configRelPath: ".codex/hooks.json", managedConfigRelPath: ".codex/hooks.json", runtime: "codex", version: pkgVersion }));
+    writeBundlePolicy(bundle, capability, targetAgents, CODEX_LIVE_HOOKS_README);
+    writeText(path.join(bundle, "install.sh"), installScript("Codex", capability, "/path/to/workspace", undefined, undefined, { configRelPath: ".codex/hooks.json", managedConfigRelPath: ".codex/hooks.json", runtime: "codex", version: pkgVersion }));
     fs.chmodSync(path.join(bundle, "install.sh"), 0o755);
 }
 function exportOpencodeAgent(spec) {
@@ -696,6 +723,7 @@ function exportOpencodeConfig() {
     }, null, 2)}\n`;
 }
 function buildOpencode(agents) {
+    const capability = BUNDLE_CAPABILITIES["opencode"];
     const bundle = path.join(dist, "opencode");
     resetDir(bundle);
     copySharedContent(bundle, "opencode", "<bundle-root>");
@@ -708,9 +736,8 @@ function buildOpencode(agents) {
     }
     writeText(path.join(bundle, ".opencode/plugins/flow-agents.js"), exportOpencodePlugin());
     writeText(path.join(bundle, "opencode.json"), exportOpencodeConfig());
-    writeText(path.join(bundle, "AGENTS.md"), exportRootAgentsMd("opencode", agents, manifest.opencode.task_dir));
-    writeText(path.join(bundle, "README.md"), exportTargetReadme("opencode", "bash install.sh /path/to/workspace"));
-    writeText(path.join(bundle, "install.sh"), installScript("opencode", "/path/to/workspace", undefined, undefined, { configRelPath: "opencode.json", managedConfigRelPath: "opencode.json", runtime: "opencode", version: pkgVersion }));
+    writeBundlePolicy(bundle, capability, agents);
+    writeText(path.join(bundle, "install.sh"), installScript("opencode", capability, "/path/to/workspace", undefined, undefined, { configRelPath: "opencode.json", managedConfigRelPath: "opencode.json", runtime: "opencode", version: pkgVersion }));
     fs.chmodSync(path.join(bundle, "install.sh"), 0o755);
 }
 function exportPiExtension() {
@@ -809,6 +836,7 @@ export default function (pi: ExtensionAPI) {
 `;
 }
 function buildPi(agents) {
+    const capability = BUNDLE_CAPABILITIES["pi"];
     const bundle = path.join(dist, "pi");
     resetDir(bundle);
     copySharedContent(bundle, "pi", "<bundle-root>");
@@ -819,9 +847,8 @@ function buildPi(agents) {
         writeText(path.join(bundle, ".pi/skills", name, "SKILL.md"), sanitizeText(readText(src), "pi", "<bundle-root>"));
     }
     writeText(path.join(bundle, ".pi/extensions/flow-agents.ts"), exportPiExtension());
-    writeText(path.join(bundle, "AGENTS.md"), exportRootAgentsMd("pi", agents, manifest.pi.task_dir));
-    writeText(path.join(bundle, "README.md"), exportTargetReadme("pi", "bash install.sh /path/to/workspace"));
-    writeText(path.join(bundle, "install.sh"), installScript("pi", "/path/to/workspace", undefined, undefined, undefined, { runtime: "pi", version: pkgVersion }));
+    writeBundlePolicy(bundle, capability, agents);
+    writeText(path.join(bundle, "install.sh"), installScript("pi", capability, "/path/to/workspace", undefined, undefined, undefined, { runtime: "pi", version: pkgVersion }));
     fs.chmodSync(path.join(bundle, "install.sh"), 0o755);
 }
 function buildCatalog(agents) {

package/build/src/tools/validate-source-tree.js

@@ -32,6 +32,7 @@ const mirroredFiles = new Map([
     // fails `npm run validate:source` instead of silently accumulating.
     ["scripts/hooks/config-protection.js", { mirror: "context/scripts/hooks/config-protection.js", allowedDifferences: [] }],
     ["scripts/hooks/lib/config-protection-remedies.js", { mirror: "context/scripts/hooks/lib/config-protection-remedies.js", allowedDifferences: [] }],
+    ["scripts/hooks/lib/continuation-turn-authority.js", { mirror: "context/scripts/hooks/lib/continuation-turn-authority.js", allowedDifferences: [] }],
     ["scripts/hooks/lib/kit-catalog.js", { mirror: "context/scripts/hooks/lib/kit-catalog.js", allowedDifferences: [] }],
     ["scripts/hooks/lib/runnable-command.js", { mirror: "context/scripts/hooks/lib/runnable-command.js", allowedDifferences: [] }],
     ["scripts/hooks/stop-goal-fit.js", { mirror: "context/scripts/hooks/stop-goal-fit.js", allowedDifferences: [] }],
@@ -83,10 +84,11 @@ const hookFilePolicies = new Map([
     ["scripts/hooks/utterance-check.js", { category: "policy hook", requiredNeedles: ["Utterance Check Hook", "FLOW_AGENTS_UTTERANCE_CHECK_ENABLED"] }],
     ["scripts/hooks/workflow-steering.js", { category: "policy hook", requiredNeedles: ["Workflow Steering Hook"] }],
     ["scripts/hooks/desktop-notify.sh", { category: "local notification helper", requiredNeedles: ["desktop-notify.sh", "osascript"] }],
-    ["scripts/hooks/lib/actor-identity.js", { category: "shared hook library", requiredNeedles: ["resolveActor", "FLOW_AGENTS_ACTOR"] }],
+    ["scripts/hooks/lib/actor-identity.js", { category: "shared hook library", requiredNeedles: ["resolveActor", "FLOW_AGENTS_ACTOR", "CODEX_THREAD_ID", "flow-agents:codex-thread:v1:"] }],
     ["scripts/hooks/lib/audit-transport.sh", { category: "shared hook library", requiredNeedles: ["audit_emit"] }],
     ["scripts/hooks/lib/codex-exit-code.js", { category: "shared hook library", requiredNeedles: ["extractExitCodeFromBanner", "readExitCodeFromRollout"] }],
     ["scripts/hooks/lib/config-protection-remedies.js", { category: "shared hook library", requiredNeedles: ["SANCTIONED_REMEDIES", "REMEDY_COMMAND_CANDIDATES"] }],
+    ["scripts/hooks/lib/continuation-turn-authority.js", { category: "shared hook library", requiredNeedles: ["issueActiveTurnAuthority", "validateActiveTurnAuthority", "validateSignedActiveTurnAssignmentAuthority"] }],
     ["scripts/hooks/lib/current-pointer.js", { category: "shared hook library", requiredNeedles: ["readCurrentPointer", "perActorCurrentFile"] }],
     ["scripts/hooks/lib/hook-flags.js", { category: "shared hook library", requiredNeedles: ["isHookEnabled"] }],
     ["scripts/hooks/lib/kit-catalog.js", { category: "shared hook library", requiredNeedles: ["readKitManifests", "workflowTriggersFor"] }],
@@ -105,6 +107,7 @@ const fixtureOwnerPolicies = new Map([
     ["evals/fixtures/backlog-provider-settings", { owners: ["evals/integration/test_effective_backlog_settings.sh"], classification: "settings precedence fixtures" }],
     ["evals/fixtures/builder-kit-workflow-state", { owners: ["evals/static/test_workflow_skills.sh"], classification: "Builder Kit workflow-state fixtures" }],
     ["evals/fixtures/console-learning-projection", { owners: ["evals/integration/test_console_learning_projection.sh"], classification: "console learning projection fixtures" }],
+    ["evals/fixtures/codex-legacy-agents", { owners: ["evals/integration/test_install_merge.sh"], classification: "exact historical Flow Agents-generated Codex AGENTS.md migration fixtures (#563)" }],
     ["evals/fixtures/economics", { owners: ["evals/integration/test_economics_record.sh"], classification: "per-run kit-economics record fixtures (#349): a transcript with .message.usage blocks, state.json/acceptance.json/critique.json join sources, a session.usage event, and the golden expected kontour.console.economics record" }],
     ["evals/fixtures/flow-kit-repository", { owners: ["evals/integration/test_flow_kit_repository.sh", "evals/integration/test_local_flow_kit_install.sh", "evals/integration/test_runtime_adapter_activation.sh", "evals/integration/test_activate_npx_context.sh", "evals/integration/test_flow_kit_install_git.sh", "evals/static/test_workflow_skills.sh"], classification: "Flow Kit repository contract fixtures" }],
     ["evals/fixtures/kit-conformance-levels", { owners: ["evals/integration/test_kit_conformance_levels.sh"], classification: "K-level conformance and consumer-target derivation fixtures" }],
@@ -113,7 +116,7 @@ const fixtureOwnerPolicies = new Map([
     ["evals/fixtures/pull-work-provider", { owners: ["evals/integration/test_pull_work_provider.sh"], classification: "work item provider normalization fixtures" }],
     ["evals/fixtures/pull-work-wip-shepherding", { owners: ["evals/static/test_workflow_skills.sh"], classification: "WIP shepherding state fixtures" }],
     ["evals/fixtures/surface-trust", { owners: ["evals/integration/test_workflow_sidecar_writer.sh"], classification: "Surface trust evidence fixtures" }],
-    ["evals/fixtures/telemetry", { owners: ["evals/integration/test_usage_cost.sh", "evals/integration/test_telemetry_usage_pipeline.sh"], classification: "hermetic Stop-hook usage transcript fixture (#defect-2026-07 telemetry-usage-cost-extraction): a multi-model JSONL transcript with .message.model + .message.usage token blocks proving real token/cost/model extraction end-to-end" }],
+    ["evals/fixtures/telemetry", { owners: ["evals/integration/test_usage_cost.sh", "evals/integration/test_telemetry_usage_pipeline.sh", "evals/integration/test_telemetry_tool_usage.sh"], classification: "hermetic Stop-hook usage transcript fixture (#defect-2026-07 telemetry-usage-cost-extraction): a multi-model JSONL transcript with .message.model + .message.usage token blocks proving real token/cost/model extraction end-to-end; also reused by the #568 slice 1 per-tool-call usage-enrichment eval (test_telemetry_tool_usage.sh), which adds usage-transcript-oversized-prefix.jsonl to prove the bounded tail-read" }],
     ["evals/fixtures/reconcile-preflight", { owners: ["evals/integration/test_reconcile_preflight.sh"], classification: "#356 reconcile-preflight shape fixtures not already covered by trust-reconcile-exploits (un-superseded disputed critique, standalone disputed session-local claim)" }],
     ["evals/fixtures/trust-reconcile-exploits", { owners: ["evals/integration/test_trust_reconcile_negatives.sh", "evals/integration/test_reconcile_preflight.sh"], classification: "WS8 trust-reconcile anti-gaming exploit fixtures (frozen negative regressions); also reused by the #356 local reconcile-preflight eval (same shapes, no forked copies)" }],
     ["evals/fixtures/trust-reconcile-mixed-bundle", { owners: ["evals/integration/test_trust_reconcile_mixed_bundle.sh", "evals/integration/test_reconcile_preflight.sh"], classification: "WS8 trust-reconcile mixed-evidence end-to-end proof fixture; also reused by the #356 reconcile-preflight eval as its CLEAN-BUNDLE (AC4) case" }],