@kontourai/flow-agents 3.8.0 → 3.10.0

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" }],

package/context/scripts/hooks/lib/continuation-turn-authority.js

@@ -0,0 +1,386 @@
+'use strict';
+
+// A transient, driver-owned capability for one adapter turn. Ed25519 proves
+// that the record was issued by the still-running driver's private key; it is
+// not a filesystem isolation boundary against a hostile same-UID process.
+
+const fs = require('fs');
+const path = require('path');
+const { createHash, generateKeyPairSync, randomBytes, randomUUID, sign, verify } = require('crypto');
+const { isDeepStrictEqual } = require('util');
+
+const SCHEMA_VERSION = '2.0';
+const FILE_NAME = 'active-turn.json';
+const MAX_ACTIVE_TURN_BYTES = 16 * 1024;
+const MAX_DRIVER_RECORD_BYTES = 1024 * 1024;
+const MAX_ASSIGNMENT_RECORD_BYTES = 1024 * 1024;
+const MAX_LOCK_RECORD_BYTES = 16 * 1024;
+const MAX_TIMEOUT_MS = 86_400_000;
+
+function activeTurnFile(sessionDir) {
+  return path.join(path.resolve(sessionDir), 'continuation-driver', FILE_NAME);
+}
+
+function issueActiveTurnAuthority(input) {
+  const sessionDir = path.resolve(input.sessionDir);
+  const parents = captureParents(sessionDir, true);
+  const issuedAt = input.now instanceof Date ? input.now : new Date();
+  const timeoutMs = input.timeoutMs;
+  assertPositiveInteger(timeoutMs, 'timeoutMs', 1, MAX_TIMEOUT_MS);
+  const assignmentActor = requiredString(input.assignmentActor, 'assignmentActor');
+  const assignmentActorStruct = requiredActorStruct(input.assignmentActorStruct, 'assignmentActorStruct');
+  const assignment = readActiveAssignment(sessionDir, parents, assignmentActor, assignmentActorStruct);
+  const keys = generateKeyPairSync('ed25519');
+  const turnSecret = randomBytes(32).toString('base64url');
+  const publicKey = keys.publicKey.export({ type: 'spki', format: 'der' }).toString('base64');
+  const publicKeyDigest = sha256(publicKey);
+  const record = {
+    schema_version: SCHEMA_VERSION,
+    run_id: requiredSafeRunId(input.runId, 'runId'),
+    definition_id: requiredString(input.definitionId, 'definitionId'),
+    issued_step: requiredString(input.currentStep, 'currentStep'),
+    iteration: requiredInteger(input.iteration, 'iteration', 1, 100),
+    max_turns: requiredInteger(input.maxTurns, 'maxTurns', 1, 100),
+    adapter_command_identity: requiredString(input.adapterCommandIdentity, 'adapterCommandIdentity'),
+    assignment_actor: assignmentActor,
+    assignment_actor_struct: assignmentActorStruct,
+    assignment_record_sha256: assignment.sha256,
+    driver_lock: {
+      pid: requiredInteger(input.lock.pid, 'lock.pid', 1, 2_147_483_647),
+      token: requiredString(input.lock.token, 'lock.token'),
+      created_at: requiredTimestamp(input.lock.created_at, 'lock.created_at'),
+    },
+    turn_secret_sha256: sha256(turnSecret),
+    public_key_spki_b64: publicKey,
+    public_key_digest: publicKeyDigest,
+    timeout_ms: timeoutMs,
+    issued_at: issuedAt.toISOString(),
+    expires_at: new Date(issuedAt.getTime() + timeoutMs).toISOString(),
+  };
+  if (record.run_id !== path.basename(sessionDir)) throw new Error('runId must match the session directory');
+  record.signature_b64 = sign(null, canonicalBytes(record), keys.privateKey).toString('base64');
+  writeRecord(sessionDir, parents, record);
+  return {
+    runId: record.run_id,
+    turnSecret,
+    publicKeyDigest,
+    record,
+    cleanup: () => removeActiveTurnAuthority(sessionDir, record.turn_secret_sha256, parents),
+  };
+}
+
+function removeActiveTurnAuthority(sessionDir, turnSecretSha256, issuedParents) {
+  try {
+    const parents = captureParents(sessionDir, false);
+    if (issuedParents && !sameParents(issuedParents, parents)) return false;
+    const file = activeTurnFile(sessionDir);
+    const loaded = readRegularJson(file, 'continuation active turn', parents, MAX_ACTIVE_TURN_BYTES);
+    if (loaded.value.turn_secret_sha256 !== turnSecretSha256) return false;
+    assertParentsStable(parents);
+    const current = fileIdentity(file, 'continuation active turn');
+    if (!sameIdentity(current, loaded.identity)) return false;
+    fs.unlinkSync(file);
+    assertParentsStable(parents);
+    return true;
+  } catch {
+    // Do not unlink through a changed parent. The signed record expires.
+    return false;
+  }
+}
+
+// Validates the signed, live assignment capability without consulting Flow's
+// current state. Public assignment-gated workflow commands use this narrow
+// fallback after ordinary actor resolution fails; Stop adds canonical-state
+// checks before treating its unfinished-gate warning as advisory.
+function validateSignedActiveTurnAssignmentAuthority(input) {
+  try {
+    const runId = requiredSafeRunId(input.runId, 'runId');
+    const turnSecret = requiredTurnSecret(input.turnSecret);
+    const sessionDir = path.resolve(input.sessionDir);
+    if (path.basename(sessionDir) !== runId) return invalid('run does not match session');
+    const parents = captureParents(sessionDir, false);
+    const record = readRegularJson(activeTurnFile(sessionDir), 'continuation active turn', parents, MAX_ACTIVE_TURN_BYTES).value;
+    validateRecord(record);
+    if (!equalText(record.run_id, runId)) return invalid('run does not match signed authority');
+    if (!equalText(record.turn_secret_sha256, sha256(turnSecret))) return invalid('turn secret does not match');
+    if (!validSignature(record)) return invalid('authority signature does not verify');
+    const assignment = readActiveAssignment(sessionDir, parents, record.assignment_actor, record.assignment_actor_struct);
+    if (!equalText(record.assignment_record_sha256, assignment.sha256)) return invalid('active assignment record changed');
+    const mission = readRegularJson(path.join(sessionDir, 'continuation-driver', 'state.json'), 'continuation driver state', parents, MAX_DRIVER_RECORD_BYTES).value;
+    if (!mission || mission.schema_version !== '1.0'
+      || mission.run_id !== record.run_id
+      || mission.definition_id !== record.definition_id
+      || mission.adapter_command_identity !== record.adapter_command_identity
+      || mission.max_turns !== record.max_turns
+      || mission.turns_started !== record.iteration
+      || mission.active_turn_step !== record.issued_step
+      || mission.active_turn_public_key_digest !== record.public_key_digest
+      || mission.status !== 'active') return invalid('driver mission does not match');
+    const lockFile = path.join(sessionDir, 'continuation-driver', 'locks', `${record.driver_lock.pid}-${record.driver_lock.token}.lock`);
+    const lock = readRegularJson(lockFile, 'continuation driver lock', parents, MAX_LOCK_RECORD_BYTES).value;
+    if (!lock || lock.schema_version !== '1.0'
+      || lock.pid !== record.driver_lock.pid
+      || lock.token !== record.driver_lock.token
+      || lock.created_at !== record.driver_lock.created_at
+      || !processAlive(lock.pid)) return invalid('driver lock is not live');
+    const now = input.now instanceof Date ? input.now : new Date();
+    if (now.getTime() < Date.parse(record.issued_at) || now.getTime() > Date.parse(record.expires_at)) return invalid('authority is expired');
+    assertParentsStable(parents);
+    return { valid: true, record };
+  } catch (error) {
+    return invalid(error && error.message ? error.message : 'authority is malformed');
+  }
+}
+
+function validateActiveTurnAuthority(input) {
+  const base = validateSignedActiveTurnAssignmentAuthority(input);
+  if (!base.valid) return base;
+  try {
+    const canonical = input.canonicalState;
+    const record = base.record;
+    // The issued step remains bound to the driver mission, while canonical
+    // Flow may advance during the adapter's Stop callback.
+    if (!canonical || canonical.status !== 'active'
+      || canonical.run_id !== record.run_id
+      || canonical.definition_id !== record.definition_id
+      || typeof canonical.current_step !== 'string' || !canonical.current_step) return invalid('canonical Flow state does not match');
+    return base;
+  } catch (error) {
+    return invalid(error && error.message ? error.message : 'canonical Flow state is malformed');
+  }
+}
+
+function invalid(reason) {
+  return { valid: false, reason };
+}
+
+function writeRecord(sessionDir, parents, record) {
+  assertParentsStable(parents);
+  const file = activeTurnFile(sessionDir);
+  if (fs.existsSync(file)) fileIdentity(file, 'continuation active turn');
+  const temp = path.join(path.dirname(file), `.${FILE_NAME}.${process.pid}.${randomUUID()}.tmp`);
+  let tempIdentity = null;
+  try {
+    fs.writeFileSync(temp, `${JSON.stringify(record)}\n`, { flag: 'wx', mode: 0o600 });
+    tempIdentity = fileIdentity(temp, 'continuation active turn temporary file');
+    assertParentsStable(parents);
+    fs.renameSync(temp, file);
+    assertParentsStable(parents);
+  } finally {
+    removeOwnedTemp(temp, tempIdentity, parents);
+  }
+}
+
+function removeOwnedTemp(temp, expected, parents) {
+  if (!expected) return;
+  try {
+    assertParentsStable(parents);
+    if (!sameIdentity(fileIdentity(temp, 'continuation active turn temporary file'), expected)) return;
+    fs.unlinkSync(temp);
+    assertParentsStable(parents);
+  } catch {
+    // Parent or temp identity changed. Leave the bounded temporary record for
+    // operator cleanup rather than unlinking through a replacement path.
+  }
+}
+
+function captureParents(sessionDir, create) {
+  const session = safeDirectory(path.resolve(sessionDir), 'session directory', create);
+  const driver = safeDirectory(path.join(session.path, 'continuation-driver'), 'continuation driver directory', create);
+  const locks = safeDirectory(path.join(driver.path, 'locks'), 'continuation driver locks directory', create);
+  const assignment = safeDirectory(path.join(path.dirname(session.path), 'assignment'), 'workflow assignment directory', false);
+  return { session, driver, locks, assignment };
+}
+
+function safeDirectory(target, label, create) {
+  if (create) fs.mkdirSync(target, { recursive: true, mode: 0o700 });
+  const stat = fs.lstatSync(target);
+  if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error(`${label} must be a non-symlink directory`);
+  const realpath = fs.realpathSync(target);
+  return { path: path.resolve(target), realpath, dev: stat.dev, ino: stat.ino };
+}
+
+function assertParentsStable(parents) {
+  for (const parent of [parents.session, parents.driver, parents.locks, parents.assignment]) {
+    const current = safeDirectory(parent.path, 'continuation authority parent', false);
+    if (!sameIdentity(parent, current) || current.realpath !== parent.realpath) throw new Error('continuation authority parent identity changed');
+  }
+}
+
+function sameParents(left, right) {
+  return ['session', 'driver', 'locks', 'assignment'].every((name) => sameIdentity(left[name], right[name]) && left[name].realpath === right[name].realpath);
+}
+
+function sameIdentity(left, right) {
+  return Boolean(left && right && left.dev === right.dev && left.ino === right.ino);
+}
+
+function readActiveAssignment(sessionDir, parents, actor, actorStruct) {
+  assertParentsStable(parents);
+  const artifactRoot = path.dirname(sessionDir);
+  const assignmentFile = path.join(parents.assignment.path, `${path.basename(sessionDir)}.json`);
+  const loaded = readRegularJson(assignmentFile, 'workflow assignment', parents, MAX_ASSIGNMENT_RECORD_BYTES);
+  const assignment = loaded.value;
+  if (!assignment || assignment.status !== 'claimed' || assignment.artifact_dir !== path.basename(sessionDir) || assignment.actor_key !== actor
+    || !isDeepStrictEqual(normalizeActorStruct(assignment.actor), normalizeActorStruct(actorStruct))) {
+    throw new Error('workflow assignment is not the active turn actor');
+  }
+  assertParentsStable(parents);
+  return { sha256: sha256(loaded.bytes) };
+}
+
+function readRegularJson(file, label, parents, maxBytes) {
+  if (parents) assertParentsStable(parents);
+  const expected = fileIdentity(file, label);
+  if (expected.size > maxBytes) throw new Error(`${label} exceeds maximum size`);
+  const noFollow = typeof fs.constants.O_NOFOLLOW === 'number' ? fs.constants.O_NOFOLLOW : 0;
+  const fd = fs.openSync(file, fs.constants.O_RDONLY | noFollow);
+  try {
+    const opened = fs.fstatSync(fd);
+    if (!opened.isFile() || opened.size > maxBytes || !sameIdentity(expected, opened)) throw new Error(`${label} identity changed while opening`);
+    const bytes = fs.readFileSync(fd);
+    const after = fs.fstatSync(fd);
+    if (!sameIdentity(expected, after)) throw new Error(`${label} identity changed while reading`);
+    const final = fileIdentity(file, label);
+    if (!sameIdentity(expected, final)) throw new Error(`${label} identity changed after reading`);
+    const value = JSON.parse(bytes.toString('utf8'));
+    if (parents) assertParentsStable(parents);
+    return { value, bytes, identity: expected };
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+function fileIdentity(file, label) {
+  const stat = fs.lstatSync(file);
+  if (stat.isSymbolicLink() || !stat.isFile()) throw new Error(`${label} must be a bounded non-symlink regular file`);
+  return { dev: stat.dev, ino: stat.ino, size: stat.size };
+}
+
+function validateRecord(record) {
+  if (!record || typeof record !== 'object' || Array.isArray(record) || record.schema_version !== SCHEMA_VERSION) throw new Error('authority schema is unsupported');
+  for (const field of ['run_id', 'definition_id', 'issued_step', 'adapter_command_identity', 'assignment_actor', 'assignment_record_sha256', 'turn_secret_sha256', 'public_key_spki_b64', 'public_key_digest', 'signature_b64', 'issued_at', 'expires_at']) requiredString(record[field], field);
+  requiredSafeRunId(record.run_id, 'run_id');
+  requiredActorStruct(record.assignment_actor_struct, 'assignment_actor_struct');
+  if (!/^[0-9a-f]{64}$/i.test(record.assignment_record_sha256)
+    || !/^[0-9a-f]{64}$/i.test(record.turn_secret_sha256)
+    || !/^[0-9a-f]{64}$/i.test(record.public_key_digest)) throw new Error('authority digest is malformed');
+  requiredInteger(record.iteration, 'iteration', 1, 100);
+  requiredInteger(record.max_turns, 'max_turns', 1, 100);
+  if (record.iteration > record.max_turns) throw new Error('authority iteration exceeds mission budget');
+  assertPositiveInteger(record.timeout_ms, 'timeout_ms', 1, MAX_TIMEOUT_MS);
+  const issued = Date.parse(requiredTimestamp(record.issued_at, 'issued_at'));
+  const expires = Date.parse(requiredTimestamp(record.expires_at, 'expires_at'));
+  if (expires !== issued + record.timeout_ms) throw new Error('authority expiry does not match timeout');
+  if (!record.driver_lock || typeof record.driver_lock !== 'object' || Array.isArray(record.driver_lock)) throw new Error('authority lock is malformed');
+  requiredInteger(record.driver_lock.pid, 'driver_lock.pid', 1, 2_147_483_647);
+  requiredString(record.driver_lock.token, 'driver_lock.token');
+  requiredTimestamp(record.driver_lock.created_at, 'driver_lock.created_at');
+}
+
+function validSignature(record) {
+  const unsigned = { ...record };
+  const signature = Buffer.from(unsigned.signature_b64, 'base64');
+  delete unsigned.signature_b64;
+  const publicKey = { key: Buffer.from(unsigned.public_key_spki_b64, 'base64'), format: 'der', type: 'spki' };
+  return equalText(sha256(unsigned.public_key_spki_b64), unsigned.public_key_digest)
+    && verify(null, canonicalBytes(unsigned), publicKey, signature);
+}
+
+function canonicalBytes(value) {
+  return Buffer.from(JSON.stringify(canonicalize(value)), 'utf8');
+}
+
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value && typeof value === 'object') return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonicalize(value[key])]));
+  return value;
+}
+
+function sha256(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function equalText(left, right) {
+  const a = Buffer.from(String(left));
+  const b = Buffer.from(String(right));
+  return a.length === b.length && require('crypto').timingSafeEqual(a, b);
+}
+
+function processAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error && error.code === 'EPERM';
+  }
+}
+
+function requiredString(value, label) {
+  if (typeof value !== 'string' || !value.trim() || value.length > 4096 || value.includes('\0')) throw new Error(`${label} must be a bounded non-empty string`);
+  return value;
+}
+
+function requiredSafeRunId(value, label) {
+  const text = requiredString(value, label);
+  if (!/^[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*$/.test(text)) throw new Error(`${label} must be a safe Flow run id`);
+  return text;
+}
+
+function requiredTurnSecret(value) {
+  const text = requiredString(value, 'turnSecret');
+  if (!/^[A-Za-z0-9_-]{43}$/.test(text)) throw new Error('turnSecret must be a 32-byte base64url secret');
+  return text;
+}
+
+function requiredActorStruct(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${label} must be an actor object`);
+  const keys = Object.keys(value);
+  if (!keys.every((key) => key === 'runtime' || key === 'session_id' || key === 'host' || key === 'human')
+    || !['runtime', 'session_id', 'host'].every((key) => Object.prototype.hasOwnProperty.call(value, key))) throw new Error(`${label} has unsupported fields`);
+  for (const key of ['runtime', 'session_id', 'host']) requiredBoundedActorField(value[key], `${label}.${key}`);
+  if (Object.prototype.hasOwnProperty.call(value, 'human') && value.human !== null) requiredBoundedActorField(value.human, `${label}.human`);
+  return {
+    runtime: value.runtime,
+    session_id: value.session_id,
+    host: value.host,
+    ...(Object.prototype.hasOwnProperty.call(value, 'human') ? { human: value.human } : {}),
+  };
+}
+
+function normalizeActorStruct(value) {
+  try {
+    const actor = requiredActorStruct(value, 'assignment actor');
+    return { ...actor, human: actor.human ?? null };
+  } catch {
+    return null;
+  }
+}
+
+function requiredBoundedActorField(value, label) {
+  if (typeof value !== 'string' || !value || value.length > 256 || /[\u0000-\u001f\u007f-\u009f]/.test(value)) throw new Error(`${label} must be a bounded non-empty string`);
+  return value;
+}
+
+function requiredInteger(value, label, min, max) {
+  if (!Number.isSafeInteger(value) || value < min || value > max) throw new Error(`${label} must be an integer from ${min} through ${max}`);
+  return value;
+}
+
+function assertPositiveInteger(value, label, min, max) {
+  requiredInteger(value, label, min, max);
+}
+
+function requiredTimestamp(value, label) {
+  const text = requiredString(value, label);
+  if (!Number.isFinite(Date.parse(text))) throw new Error(`${label} must be an ISO timestamp`);
+  return text;
+}
+
+module.exports = {
+  activeTurnFile,
+  issueActiveTurnAuthority,
+  removeActiveTurnAuthority,
+  validateActiveTurnAuthority,
+  validateSignedActiveTurnAssignmentAuthority,
+};