agentxchain 2.150.0 → 2.151.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "2.150.0",
+  "version": "2.151.0",
   "description": "CLI for AgentXchain — governed multi-agent software delivery",
   "type": "module",
   "bin": {
@@ -37,6 +37,7 @@
     "bump:release": "bash scripts/release-bump.sh",
     "sync:homebrew": "bash scripts/sync-homebrew.sh",
     "verify:post-publish": "bash scripts/verify-post-publish.sh",
+    "collect:pack-sha-diagnostic": "node scripts/collect-pack-sha-diagnostic.mjs",
     "build:macos": "bun build bin/agentxchain.js --compile --target=bun-darwin-arm64 --outfile=dist/agentxchain-macos-arm64",
     "build:linux": "bun build bin/agentxchain.js --compile --target=bun-linux-x64 --outfile=dist/agentxchain-linux-x64",
     "publish:npm": "bash scripts/publish-npm.sh"

package/scripts/collect-pack-sha-diagnostic.mjs

@@ -0,0 +1,344 @@
+#!/usr/bin/env node
+/**
+ * Collect pack-SHA diagnostic evidence from `publish-npm-on-tag.yml` runs.
+ *
+ * Purpose:
+ *   Turn 129 (`DEC-PUBLISH-WORKFLOW-PACK-SHA-DIAGNOSTIC-ONLY-001`) added
+ *   runner-local `npm pack` SHA capture + registry `dist.shasum`/`dist.integrity`
+ *   comparison to the publish workflow as diagnostic-only evidence. Each
+ *   published tag now emits `PACK_SHA_DIAGNOSTIC:` and `PACK_INTEGRITY_DIAGNOSTIC:`
+ *   log lines with MATCH/MISMATCH verdicts.
+ *
+ *   A real reproducible-publish gate cannot be designed until we have ≥3 release
+ *   cycles of evidence. This script turns the per-run log lines into a
+ *   multi-release evidence view so the threshold can be evaluated at a glance.
+ *
+ * Behavior:
+ *   Default: uses `gh run list` to fetch the last N `publish-npm-on-tag.yml`
+ *   runs, then `gh run view <id> --log` to scrape the two diagnostic tags from
+ *   each run's logs, and prints a table summary plus aggregate MATCH/MISMATCH
+ *   counts.
+ *
+ *   Test / offline mode: `--log-file <path>` parses a single saved log instead
+ *   of calling `gh`. Useful for unit tests and local debugging without GH auth.
+ *
+ * Usage:
+ *   cd cli && npm run collect:pack-sha-diagnostic --                  # last 10 runs
+ *   cd cli && npm run collect:pack-sha-diagnostic -- --limit 20
+ *   node cli/scripts/collect-pack-sha-diagnostic.mjs                    # direct path
+ *   node cli/scripts/collect-pack-sha-diagnostic.mjs --limit 20
+ *   node cli/scripts/collect-pack-sha-diagnostic.mjs --format json
+ *   node cli/scripts/collect-pack-sha-diagnostic.mjs --workflow publish-npm-on-tag.yml
+ *   node cli/scripts/collect-pack-sha-diagnostic.mjs --log-file /tmp/run.log
+ *
+ * How to read the output:
+ *   - `MATCH` means the workflow's runner-local pack value matched the npm
+ *     registry value for that release run.
+ *   - `MISMATCH` means the runner-local pack value differed from registry
+ *     truth. Treat it as investigation evidence, not an automatic release
+ *     failure.
+ *   - `unavailable` means the diagnostic ran but could not form a comparison
+ *     (for example, registry metadata was not ready).
+ *   - `missing` means the diagnostic tag was absent, usually because the run
+ *     was an already-published rerun and skipped local packing.
+ *   - Only non-rerun `MATCH` verdicts count toward the "≥3 MATCH" evidence
+ *     threshold from `DEC-PUBLISH-WORKFLOW-PACK-SHA-DIAGNOSTIC-ONLY-001`.
+ *     That threshold only permits designing a future gate; it is not a gate
+ *     by itself.
+ *
+ * Diagnostic-only. This script does not gate releases, mutate state, or fail
+ * on MISMATCH. It prints evidence; a gate is a future decision.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+
+const DEFAULT_WORKFLOW = 'publish-npm-on-tag.yml';
+const DEFAULT_LIMIT = 10;
+
+/**
+ * Parse a publish workflow log for the Turn 129 diagnostic tags.
+ *
+ * Returns a plain object with:
+ *   - shaVerdict:       'MATCH' | 'MISMATCH' | 'unavailable' | 'missing'
+ *   - shaDetail:        the line body after the ':' (MATCH/MISMATCH reason) or null
+ *   - integrityVerdict: 'MATCH' | 'MISMATCH' | 'unavailable' | 'missing'
+ *   - integrityDetail:  the line body after the ':' or null
+ *   - version:          the `agentxchain@X.Y.Z` version extracted from the SHA tag, or null
+ *
+ * A log with no `PACK_SHA_DIAGNOSTIC:` tag returns shaVerdict = 'missing'
+ * (the diagnostic step did not run — e.g. `already_published` rerun).
+ *
+ * A log whose SHA tag says "unavailable" (registry dist missing, runner pack
+ * failed) returns shaVerdict = 'unavailable' — distinct from MATCH/MISMATCH
+ * because the diagnostic could not form a verdict.
+ */
+export function parseDiagnosticLines(logText) {
+  const shaRegex = /PACK_SHA_DIAGNOSTIC:\s*([^\n]+)/;
+  const integrityRegex = /PACK_INTEGRITY_DIAGNOSTIC:\s*([^\n]+)/;
+
+  const classifyVerdict = (detail) => {
+    if (!detail) return 'missing';
+    const head = detail.trim().split(/\s+/)[0] ?? '';
+    if (head === 'MATCH') return 'MATCH';
+    if (head === 'MISMATCH') return 'MISMATCH';
+    return 'unavailable';
+  };
+
+  const shaMatch = logText.match(shaRegex);
+  const integrityMatch = logText.match(integrityRegex);
+
+  const shaDetail = shaMatch ? shaMatch[1].trim() : null;
+  const integrityDetail = integrityMatch ? integrityMatch[1].trim() : null;
+
+  const shaVerdict = shaMatch ? classifyVerdict(shaDetail) : 'missing';
+  const integrityVerdict = integrityMatch
+    ? classifyVerdict(integrityDetail)
+    : 'missing';
+
+  // Try to pull `agentxchain@X.Y.Z` from either diagnostic line.
+  let version = null;
+  const versionSource = `${shaDetail ?? ''} ${integrityDetail ?? ''}`;
+  const versionMatch = versionSource.match(/agentxchain@(\d+\.\d+\.\d+)/);
+  if (versionMatch) version = versionMatch[1];
+
+  return { shaVerdict, shaDetail, integrityVerdict, integrityDetail, version };
+}
+
+/**
+ * Render an array of run records as a fixed-width text table.
+ * Pure function, no side effects — safe to call from tests.
+ */
+export function renderTable(rows) {
+  if (rows.length === 0) {
+    return 'No publish-npm-on-tag.yml runs found.';
+  }
+  const header = ['version', 'run_id', 'sha', 'integrity', 'created_at', 'url'];
+  const body = rows.map((r) => [
+    r.version ?? '-',
+    String(r.runId ?? '-'),
+    r.shaVerdict,
+    r.integrityVerdict,
+    r.createdAt ?? '-',
+    r.url ?? '-',
+  ]);
+  const widths = header.map((h, i) =>
+    Math.max(h.length, ...body.map((row) => row[i].length)),
+  );
+  const pad = (cells) =>
+    cells.map((c, i) => c.padEnd(widths[i])).join('  ');
+  const lines = [pad(header), pad(widths.map((w) => '-'.repeat(w)))];
+  for (const row of body) lines.push(pad(row));
+  return lines.join('\n');
+}
+
+/**
+ * Summarize MATCH/MISMATCH/unavailable/missing counts across rows.
+ * Used by `renderTable` callers to emit the "≥3 releases of MATCH" threshold
+ * status described in DEC-PUBLISH-WORKFLOW-PACK-SHA-DIAGNOSTIC-ONLY-001.
+ */
+export function summarize(rows) {
+  const count = (field) => {
+    const tally = { MATCH: 0, MISMATCH: 0, unavailable: 0, missing: 0 };
+    for (const r of rows) {
+      const verdict = r[field];
+      if (verdict in tally) tally[verdict] += 1;
+    }
+    return tally;
+  };
+  const sha = count('shaVerdict');
+  const integrity = count('integrityVerdict');
+  return { totalRuns: rows.length, sha, integrity };
+}
+
+function parseArgs(argv) {
+  const args = {
+    limit: DEFAULT_LIMIT,
+    workflow: DEFAULT_WORKFLOW,
+    format: 'table',
+    logFile: null,
+    repo: null,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--limit') {
+      args.limit = Number(argv[i + 1]);
+      i += 1;
+    } else if (arg === '--workflow') {
+      args.workflow = argv[i + 1];
+      i += 1;
+    } else if (arg === '--format') {
+      args.format = argv[i + 1];
+      i += 1;
+    } else if (arg === '--log-file') {
+      args.logFile = argv[i + 1];
+      i += 1;
+    } else if (arg === '--repo') {
+      args.repo = argv[i + 1];
+      i += 1;
+    } else if (arg === '--help' || arg === '-h') {
+      args.help = true;
+    } else {
+      throw new Error(`unknown argument: ${arg}`);
+    }
+  }
+  if (!Number.isInteger(args.limit) || args.limit <= 0) {
+    throw new Error(`--limit must be a positive integer, got: ${args.limit}`);
+  }
+  if (!['table', 'json'].includes(args.format)) {
+    throw new Error(`--format must be "table" or "json", got: ${args.format}`);
+  }
+  return args;
+}
+
+function printHelp() {
+  process.stdout.write(
+    [
+      'Usage: node cli/scripts/collect-pack-sha-diagnostic.mjs [options]',
+      '',
+      'Options:',
+      '  --limit <N>         Number of recent runs to inspect (default: 10)',
+      '  --workflow <name>   Workflow filename (default: publish-npm-on-tag.yml)',
+      '  --format table|json Output format (default: table)',
+      '  --log-file <path>   Parse a single saved log file instead of calling gh',
+      '  --repo <owner/name> Override repo (defaults to gh current repo)',
+      '  -h, --help          Show this help',
+      '',
+      'Emits MATCH/MISMATCH/unavailable/missing counts for PACK_SHA_DIAGNOSTIC',
+      'and PACK_INTEGRITY_DIAGNOSTIC tags. Diagnostic-only; never fails.',
+      '',
+    ].join('\n'),
+  );
+}
+
+function ghJson(args) {
+  const out = execFileSync('gh', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  return JSON.parse(out);
+}
+
+function ghText(args) {
+  return execFileSync('gh', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+}
+
+function collectFromGh({ limit, workflow, repo }) {
+  const listArgs = [
+    'run', 'list',
+    '--workflow', workflow,
+    '--limit', String(limit),
+    '--json', 'databaseId,displayTitle,conclusion,createdAt,url,headBranch,headSha',
+  ];
+  if (repo) listArgs.push('--repo', repo);
+
+  let runs;
+  try {
+    runs = ghJson(listArgs);
+  } catch (err) {
+    throw new Error(
+      `Failed to list workflow runs via gh. Is the GitHub CLI installed and authenticated? (${err.message})`,
+    );
+  }
+
+  const rows = [];
+  for (const run of runs) {
+    const viewArgs = ['run', 'view', String(run.databaseId), '--log'];
+    if (repo) viewArgs.push('--repo', repo);
+    let log = '';
+    try {
+      log = ghText(viewArgs);
+    } catch (err) {
+      // gh run view --log fails when logs are expired (>90d) or mid-run.
+      // Record the run with missing verdicts rather than aborting the whole sweep.
+      rows.push({
+        runId: run.databaseId,
+        displayTitle: run.displayTitle,
+        conclusion: run.conclusion,
+        createdAt: run.createdAt,
+        url: run.url,
+        headBranch: run.headBranch,
+        headSha: run.headSha,
+        shaVerdict: 'missing',
+        integrityVerdict: 'missing',
+        shaDetail: null,
+        integrityDetail: null,
+        version: null,
+        logError: err.message,
+      });
+      continue;
+    }
+    const parsed = parseDiagnosticLines(log);
+    rows.push({
+      runId: run.databaseId,
+      displayTitle: run.displayTitle,
+      conclusion: run.conclusion,
+      createdAt: run.createdAt,
+      url: run.url,
+      headBranch: run.headBranch,
+      headSha: run.headSha,
+      ...parsed,
+    });
+  }
+  return rows;
+}
+
+async function main(argv) {
+  let args;
+  try {
+    args = parseArgs(argv);
+  } catch (err) {
+    process.stderr.write(`collect-pack-sha-diagnostic: ${err.message}\n`);
+    printHelp();
+    process.exit(2);
+  }
+  if (args.help) {
+    printHelp();
+    return;
+  }
+
+  let rows;
+  if (args.logFile) {
+    const log = readFileSync(args.logFile, 'utf8');
+    rows = [{ runId: null, createdAt: null, url: args.logFile, ...parseDiagnosticLines(log) }];
+  } else {
+    rows = collectFromGh({ limit: args.limit, workflow: args.workflow, repo: args.repo });
+  }
+
+  if (args.format === 'json') {
+    process.stdout.write(JSON.stringify({ rows, summary: summarize(rows) }, null, 2));
+    process.stdout.write('\n');
+    return;
+  }
+
+  const table = renderTable(rows);
+  const summary = summarize(rows);
+  process.stdout.write(`${table}\n\n`);
+  process.stdout.write(
+    [
+      `Runs inspected:        ${summary.totalRuns}`,
+      `SHA MATCH:             ${summary.sha.MATCH}`,
+      `SHA MISMATCH:          ${summary.sha.MISMATCH}`,
+      `SHA unavailable:       ${summary.sha.unavailable}`,
+      `SHA missing:           ${summary.sha.missing}  (rerun / no diagnostic)`,
+      `INTEGRITY MATCH:       ${summary.integrity.MATCH}`,
+      `INTEGRITY MISMATCH:    ${summary.integrity.MISMATCH}`,
+      `INTEGRITY unavailable: ${summary.integrity.unavailable}`,
+      `INTEGRITY missing:     ${summary.integrity.missing}`,
+      '',
+      'Diagnostic-only. ≥3 MATCH on both SHA + INTEGRITY is the threshold',
+      'named in DEC-PUBLISH-WORKFLOW-PACK-SHA-DIAGNOSTIC-ONLY-001 before any',
+      'reproducible-publish gate can be designed.',
+      '',
+    ].join('\n'),
+  );
+}
+
+// Only run main when invoked directly (not when imported by tests).
+const invokedDirectly =
+  import.meta.url === `file://${process.argv[1]}` ||
+  (process.argv[1] && import.meta.url.endsWith(process.argv[1].replace(/^.*\//, '')));
+
+if (invokedDirectly) {
+  main(process.argv.slice(2)).catch((err) => {
+    process.stderr.write(`collect-pack-sha-diagnostic: ${err.stack || err.message}\n`);
+    process.exit(1);
+  });
+}

package/src/commands/init.js

@@ -195,15 +195,44 @@ const GOVERNED_ROUTING = {
 const GOVERNED_GATES = {
   planning_signoff: {
     requires_files: ['.planning/PM_SIGNOFF.md', '.planning/ROADMAP.md', '.planning/SYSTEM_SPEC.md'],
-    requires_human_approval: true
+    requires_human_approval: true,
+    credentialed: false
   },
   implementation_complete: {
     requires_files: ['.planning/IMPLEMENTATION_NOTES.md'],
-    requires_verification_pass: true
+    requires_verification_pass: true,
+    credentialed: false
   },
   qa_ship_verdict: {
     requires_files: ['.planning/acceptance-matrix.md', '.planning/ship-verdict.md', '.planning/RELEASE_NOTES.md'],
-    requires_human_approval: true
+    requires_human_approval: true,
+    requires_verification_pass: true,
+    credentialed: false
+  }
+};
+
+const GOVERNED_APPROVAL_POLICY = {
+  phase_transitions: {
+    default: 'require_human',
+    rules: [
+      {
+        from_phase: 'planning',
+        to_phase: 'implementation',
+        action: 'auto_approve',
+        when: {
+          gate_passed: true,
+          credentialed_gate: false
+        }
+      }
+    ]
+  },
+  run_completion: {
+    action: 'auto_approve',
+    when: {
+      gate_passed: true,
+      all_phases_visited: true,
+      credentialed_gate: false
+    }
   }
 };
 
@@ -713,6 +742,7 @@ function buildScaffoldConfigFromTemplate(template, localDevRuntime, workflowKitC
 
   const routing = cloneJsonCompatible(blueprint?.routing || GOVERNED_ROUTING);
   const gates = cloneJsonCompatible(blueprint?.gates || GOVERNED_GATES);
+  const approvalPolicy = cloneJsonCompatible(blueprint?.approval_policy || GOVERNED_APPROVAL_POLICY);
   const effectiveWorkflowKitConfig = workflowKitConfig || cloneJsonCompatible(blueprint?.workflow_kit || null);
   const prompts = Object.fromEntries(
     Object.keys(roles).map((roleId) => [roleId, `.agentxchain/prompts/${roleId}.md`])
@@ -725,6 +755,7 @@ function buildScaffoldConfigFromTemplate(template, localDevRuntime, workflowKitC
     runtimes,
     routing,
     gates,
+    approvalPolicy,
     policies,
     prompts,
     workflowKitConfig: effectiveWorkflowKitConfig,
@@ -778,7 +809,7 @@ export function scaffoldGoverned(dir, projectName, projectId, templateId = 'gene
   const template = loadGovernedTemplate(templateId);
   const { runtime: localDevRuntime } = resolveGovernedLocalDevRuntime(runtimeOptions);
   const scaffoldConfig = buildScaffoldConfigFromTemplate(template, localDevRuntime, workflowKitConfig, runtimeOptions);
-  const { roles, runtimes, routing, gates, policies, prompts, workflowKitConfig: effectiveWorkflowKitConfig } = scaffoldConfig;
+  const { roles, runtimes, routing, gates, approvalPolicy, policies, prompts, workflowKitConfig: effectiveWorkflowKitConfig } = scaffoldConfig;
   const scaffoldWorkflowKitConfig = effectiveWorkflowKitConfig
     ? normalizeWorkflowKit(effectiveWorkflowKitConfig, Object.keys(routing))
     : null;
@@ -804,6 +835,7 @@ export function scaffoldGoverned(dir, projectName, projectId, templateId = 'gene
     runtimes,
     routing,
     gates,
+    approval_policy: approvalPolicy,
     budget: {
       per_turn_max_usd: 2.0,
       per_run_max_usd: 50.0,

package/src/lib/adapters/local-cli-adapter.js

@@ -41,6 +41,7 @@ const DIAGNOSTIC_ENV_KEYS = [
   'AGENTXCHAIN_TURN_ID',
 ];
 const DIAGNOSTIC_STDERR_EXCERPT_LIMIT = 800;
+const DEFAULT_STARTUP_WATCHDOG_MS = 180_000;
 
 /**
  * Launch a local CLI subprocess for a governed turn.
@@ -579,7 +580,7 @@ function resolveStartupWatchdogMs(config, runtime) {
   if (Number.isInteger(config?.run_loop?.startup_watchdog_ms) && config.run_loop.startup_watchdog_ms > 0) {
     return config.run_loop.startup_watchdog_ms;
   }
-  return 30_000;
+  return DEFAULT_STARTUP_WATCHDOG_MS;
 }
 
 /**

package/src/lib/approval-policy.js

@@ -37,7 +37,26 @@ export function evaluateApprovalPolicy({ gateResult, gateType, state, config })
   return evaluatePhaseTransitionPolicy({ gateResult, state, config, policy });
 }
 
+// BUG-59 (DEC-BUG59-CREDENTIALED-GATE-HARD-STOP-001): gate definitions may
+// carry `credentialed: true` to mark gates protecting external, irreversible,
+// or operator-owned credentialed actions. Credentialed gates are never
+// auto-approvable by policy, even under a catch-all `default: auto_approve`
+// rule. The guard runs before any rule evaluation so a missing `when` block
+// cannot bypass it.
+function isCredentialedGate(config, gateId) {
+  if (!gateId) return false;
+  return config?.gates?.[gateId]?.credentialed === true;
+}
+
 function evaluateRunCompletionPolicy({ gateResult, state, config, policy }) {
+  if (isCredentialedGate(config, gateResult?.gate_id)) {
+    return {
+      action: 'require_human',
+      matched_rule: null,
+      reason: 'credentialed gate — policy auto-approval forbidden',
+    };
+  }
+
   const rc = policy.run_completion;
   if (!rc || !rc.action) {
     return { action: 'require_human', matched_rule: null, reason: 'no run_completion policy' };
@@ -59,6 +78,14 @@ function evaluateRunCompletionPolicy({ gateResult, state, config, policy }) {
 }
 
 function evaluatePhaseTransitionPolicy({ gateResult, state, config, policy }) {
+  if (isCredentialedGate(config, gateResult?.gate_id)) {
+    return {
+      action: 'require_human',
+      matched_rule: null,
+      reason: 'credentialed gate — policy auto-approval forbidden',
+    };
+  }
+
   const pt = policy.phase_transitions;
   if (!pt) {
     return { action: 'require_human', matched_rule: null, reason: 'no phase_transitions policy' };
@@ -120,6 +147,23 @@ function checkConditions(when, { gateResult, state, config }) {
     }
   }
 
+  // credentialed_gate (BUG-59, DEC-BUG59-CREDENTIALED-GATE-PREDICATE-NEGATIVE-ONLY-001):
+  // only `false` is a valid runtime value — asserts the gate is NOT credentialed
+  // as a defensive precondition. Credentialed gates are hard-stopped upstream so
+  // this predicate never sees them when value is `false` (matches → condition ok).
+  // Value `true` is treated as unmet because the hard-stop prevents credentialed
+  // gates from reaching condition evaluation anyway; schema validation (slice 2)
+  // will reject `true` at config load time for unambiguous intent.
+  if (Object.prototype.hasOwnProperty.call(when, 'credentialed_gate')) {
+    const gateIsCredentialed = config?.gates?.[gateResult?.gate_id]?.credentialed === true;
+    if (when.credentialed_gate === false && gateIsCredentialed) {
+      return { ok: false, reason: 'condition credentialed_gate: false not met — gate is credentialed' };
+    }
+    if (when.credentialed_gate === true) {
+      return { ok: false, reason: 'condition credentialed_gate: true not supported — credentialed gates are hard-stopped upstream' };
+    }
+  }
+
   // all_phases_visited: every routing phase must appear in history
   if (when.all_phases_visited === true) {
     const routingPhases = Object.keys(config.routing || {});

package/src/lib/governed-state.js

@@ -2665,6 +2665,91 @@ export function reconcilePhaseAdvanceBeforeDispatch(root, config, state = null)
   });
 
   if (gateResult.action === 'awaiting_human_approval') {
+    // BUG-59 (DEC-BUG59-PLAN-LAYERED-FIX-001, slice 3): before falling back to
+    // the BUG-52 "human already unblocked" advancement path, consult
+    // approval_policy. If the configured policy auto-approves this transition
+    // (and the gate is not credentialed), advance directly and write an
+    // `approval_policy` ledger entry matching the accepted-turn path shape at
+    // governed-state.js:4909-4919. Credentialed gates are hard-stopped inside
+    // evaluateApprovalPolicy per DEC-BUG59-CREDENTIALED-GATE-HARD-STOP-001, so
+    // a credentialed gate lands here with action === 'require_human' and falls
+    // through to the existing approvePhaseTransition path (which itself
+    // requires paused/blocked status produced by a real human unblock).
+    const approvalResult = evaluateApprovalPolicy({
+      gateResult,
+      gateType: 'phase_transition',
+      state: { ...currentState, history: historyEntries },
+      config,
+    });
+
+    if (approvalResult.action === 'auto_approve') {
+      const now = new Date().toISOString();
+      const prevPhase = currentState.phase;
+      const nextState = {
+        ...currentState,
+        phase: gateResult.next_phase,
+        phase_entered_at: now,
+        blocked_on: null,
+        blocked_reason: null,
+        last_gate_failure: null,
+        pending_phase_transition: null,
+        queued_phase_transition: null,
+        phase_gate_status: {
+          ...(currentState.phase_gate_status || {}),
+          [gateResult.gate_id || 'no_gate']: 'passed',
+        },
+      };
+      writeState(root, nextState);
+      appendJsonl(root, LEDGER_PATH, {
+        type: 'approval_policy',
+        gate_type: 'phase_transition',
+        action: 'auto_approve',
+        matched_rule: approvalResult.matched_rule,
+        from_phase: prevPhase,
+        to_phase: gateResult.next_phase,
+        reason: approvalResult.reason,
+        gate_id: gateResult.gate_id || null,
+        timestamp: now,
+      });
+      const retiredIntentIds = retireApprovedPhaseScopedIntents(root, nextState, config, prevPhase, now);
+      if (retiredIntentIds.length > 0) {
+        emitRunEvent(root, 'intent_retired_by_phase_advance', {
+          run_id: nextState.run_id,
+          phase: nextState.phase,
+          status: nextState.status,
+          turn: phaseSource.turn_id ? { turn_id: phaseSource.turn_id, role_id: phaseSource.role || phaseSource.assigned_role || null } : undefined,
+          payload: {
+            exited_phase: prevPhase,
+            entered_phase: gateResult.next_phase,
+            retired_count: retiredIntentIds.length,
+            retired_intent_ids: retiredIntentIds,
+          },
+        });
+      }
+      emitRunEvent(root, 'phase_entered', {
+        run_id: nextState.run_id,
+        phase: nextState.phase,
+        status: nextState.status,
+        turn: phaseSource.turn_id ? { turn_id: phaseSource.turn_id, role_id: phaseSource.role || phaseSource.assigned_role || null } : undefined,
+        payload: {
+          from: prevPhase,
+          to: gateResult.next_phase,
+          gate_id: gateResult.gate_id || 'no_gate',
+          trigger: 'auto_approved',
+        },
+      });
+      return {
+        ok: true,
+        state: attachLegacyCurrentTurnAlias(nextState),
+        advanced: true,
+        from_phase: prevPhase,
+        to_phase: gateResult.next_phase,
+        gate_id: gateResult.gate_id || null,
+        gateResult,
+        approval_policy: approvalResult,
+      };
+    }
+
     const pausedState = {
       ...currentState,
       status: 'paused',
@@ -2689,6 +2774,7 @@ export function reconcilePhaseAdvanceBeforeDispatch(root, config, state = null)
       to_phase: approved.state?.phase || gateResult.next_phase || null,
       gate_id: gateResult.gate_id || null,
       gateResult,
+      approval_policy: approvalResult,
     };
   }
 
@@ -5499,6 +5585,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
       status: 'completed',
       payload: { completed_at: updatedState.completed_at || now },
     });
+    recordRunHistory(root, updatedState, config, 'completed');
   }
 
   // Session checkpoint — non-fatal, written after every successful acceptance

package/src/lib/governed-templates.js

@@ -83,6 +83,7 @@ const VALID_SCAFFOLD_BLUEPRINT_KEYS = new Set([
   'gates',
   'policies',
   'workflow_kit',
+  'approval_policy',
 ]);
 
 function validateScaffoldBlueprint(scaffoldBlueprint, errors) {

package/src/lib/normalized-config.js

@@ -557,6 +557,7 @@ export function validateV4Config(data, projectRoot) {
   // Gates (optional but validated if present)
   if (data.gates) {
     validateGateActionsConfig(data.gates, errors);
+    validateGateCredentialedConfig(data.gates, errors);
     if (data.gates && typeof data.gates === 'object' && !Array.isArray(data.gates) && data.routing) {
       for (const [, route] of Object.entries(data.routing)) {
         if (route.exit_gate && !data.gates[route.exit_gate]) {
@@ -996,6 +997,21 @@ export function validateWorkflowKitConfig(wk, routing, roles, runtimes = {}) {
 
 const VALID_APPROVAL_ACTIONS = ['auto_approve', 'require_human'];
 
+function validateGateCredentialedConfig(gates, errors) {
+  if (!gates || typeof gates !== 'object' || Array.isArray(gates)) {
+    return;
+  }
+
+  for (const [gateId, gate] of Object.entries(gates)) {
+    if (!gate || typeof gate !== 'object' || Array.isArray(gate)) {
+      continue;
+    }
+    if (gate.credentialed !== undefined && typeof gate.credentialed !== 'boolean') {
+      errors.push(`gates.${gateId}.credentialed must be a boolean when provided`);
+    }
+  }
+}
+
 /**
  * Validate the approval_policy config section.
  * Returns an array of error strings.
@@ -1098,6 +1114,13 @@ function validateApprovalWhen(when, prefix) {
   if (when.all_phases_visited !== undefined && typeof when.all_phases_visited !== 'boolean') {
     errors.push(`${prefix}.when.all_phases_visited must be a boolean`);
   }
+  if (when.credentialed_gate !== undefined) {
+    if (typeof when.credentialed_gate !== 'boolean') {
+      errors.push(`${prefix}.when.credentialed_gate must be a boolean`);
+    } else if (when.credentialed_gate !== false) {
+      errors.push(`${prefix}.when.credentialed_gate must be false when provided (DEC-BUG59-CREDENTIALED-GATE-PREDICATE-NEGATIVE-ONLY-001)`);
+    }
+  }
   return errors;
 }
 

package/src/lib/schemas/agentxchain-config.schema.json

@@ -61,7 +61,14 @@
       "type": ["array", "object"]
     },
     "approval_policy": {
-      "type": ["object", "null"]
+      "oneOf": [
+        {
+          "$ref": "#/$defs/approval_policy"
+        },
+        {
+          "type": "null"
+        }
+      ]
     },
     "timeouts": {
       "type": ["object", "null"]
@@ -91,7 +98,7 @@
         "startup_watchdog_ms": {
           "type": "integer",
           "minimum": 1,
-          "description": "Milliseconds to wait after dispatch for worker attach/first-output proof before retaining the turn as failed_start. Default 30000."
+          "description": "Milliseconds to wait after dispatch for worker attach/first-output proof before retaining the turn as failed_start. Default 180000."
         },
         "stale_turn_threshold_ms": {
           "type": "integer",
@@ -220,6 +227,87 @@
         },
         "requires_verification_pass": {
           "type": "boolean"
+        },
+        "credentialed": {
+          "type": "boolean",
+          "description": "When true, this gate protects a credentialed, irreversible, or operator-owned action and cannot be auto-approved by approval_policy."
+        }
+      },
+      "additionalProperties": true
+    },
+    "approval_policy": {
+      "type": "object",
+      "properties": {
+        "phase_transitions": {
+          "$ref": "#/$defs/approval_phase_transitions"
+        },
+        "run_completion": {
+          "$ref": "#/$defs/approval_run_completion"
+        }
+      },
+      "additionalProperties": true
+    },
+    "approval_phase_transitions": {
+      "type": "object",
+      "properties": {
+        "default": {
+          "enum": ["auto_approve", "require_human"]
+        },
+        "rules": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/approval_phase_rule"
+          }
+        }
+      },
+      "additionalProperties": true
+    },
+    "approval_phase_rule": {
+      "type": "object",
+      "properties": {
+        "from_phase": {
+          "$ref": "#/$defs/non_empty_string"
+        },
+        "to_phase": {
+          "$ref": "#/$defs/non_empty_string"
+        },
+        "action": {
+          "enum": ["auto_approve", "require_human"]
+        },
+        "when": {
+          "$ref": "#/$defs/approval_when"
+        }
+      },
+      "additionalProperties": true
+    },
+    "approval_run_completion": {
+      "type": "object",
+      "properties": {
+        "action": {
+          "enum": ["auto_approve", "require_human"]
+        },
+        "when": {
+          "$ref": "#/$defs/approval_when"
+        }
+      },
+      "additionalProperties": true
+    },
+    "approval_when": {
+      "type": "object",
+      "properties": {
+        "gate_passed": {
+          "type": "boolean"
+        },
+        "roles_participated": {
+          "$ref": "#/$defs/string_array"
+        },
+        "all_phases_visited": {
+          "type": "boolean"
+        },
+        "credentialed_gate": {
+          "type": "boolean",
+          "enum": [false],
+          "description": "Only false is valid. Credentialed gates are hard-stopped before policy rule matching."
         }
       },
       "additionalProperties": true

package/src/lib/stale-turn-watchdog.js

@@ -4,7 +4,7 @@
  * Two-tier lazy idle-threshold detection:
  *
  * 1. **Fast startup watchdog (BUG-51):** if an active turn has been
- *    `dispatched`/`starting`/`running` for >30 seconds with NO startup proof
+ *    `dispatched`/`starting`/`running` for >180 seconds with NO startup proof
  *    (no first-byte output recorded on the turn or in dispatch-progress) and
  *    NO staged result, it is a "ghost turn" — the subprocess never reached a
  *    healthy running state. Transitions to `failed_start` immediately.
@@ -24,7 +24,7 @@
  * requiring a background daemon.
  *
  * Default thresholds:
- *   - Startup watchdog: 30 seconds (configurable via run_loop.startup_watchdog_ms
+ *   - Startup watchdog: 180 seconds (configurable via run_loop.startup_watchdog_ms
  *     or runtimes.<id>.startup_watchdog_ms for local_cli runtimes)
  *   - local_cli stale turns: 10 minutes
  *   - api_proxy stale turns: 5 minutes
@@ -42,7 +42,7 @@ import { hasMeaningfulStagedResult } from './staged-result-proof.js';
 
 const DEFAULT_LOCAL_CLI_THRESHOLD_MS = 10 * 60 * 1000; // 10 minutes
 const DEFAULT_API_PROXY_THRESHOLD_MS = 5 * 60 * 1000;  // 5 minutes
-const DEFAULT_STARTUP_WATCHDOG_MS = 30 * 1000;          // 30 seconds (BUG-51)
+const DEFAULT_STARTUP_WATCHDOG_MS = 180 * 1000;         // 180 seconds (BUG-54)
 const LEGACY_STAGING_PATH = '.agentxchain/staging/turn-result.json';
 
 /**

package/src/templates/governed/enterprise-app.json

@@ -125,21 +125,51 @@
     "gates": {
       "planning_signoff": {
         "requires_files": [".planning/PM_SIGNOFF.md", ".planning/ROADMAP.md", ".planning/SYSTEM_SPEC.md"],
-        "requires_human_approval": true
+        "requires_human_approval": true,
+        "credentialed": false
       },
       "architecture_review": {
-        "requires_files": [".planning/ARCHITECTURE.md"]
+        "requires_files": [".planning/ARCHITECTURE.md"],
+        "credentialed": false
       },
       "implementation_complete": {
         "requires_files": [".planning/IMPLEMENTATION_NOTES.md"],
-        "requires_verification_pass": true
+        "requires_verification_pass": true,
+        "credentialed": false
       },
       "security_review_signoff": {
-        "requires_files": [".planning/SECURITY_REVIEW.md"]
+        "requires_files": [".planning/SECURITY_REVIEW.md"],
+        "credentialed": false
       },
       "qa_ship_verdict": {
         "requires_files": [".planning/acceptance-matrix.md", ".planning/ship-verdict.md", ".planning/RELEASE_NOTES.md"],
-        "requires_human_approval": true
+        "requires_human_approval": true,
+        "requires_verification_pass": true,
+        "credentialed": false
+      }
+    },
+    "approval_policy": {
+      "phase_transitions": {
+        "default": "require_human",
+        "rules": [
+          {
+            "from_phase": "planning",
+            "to_phase": "architecture",
+            "action": "auto_approve",
+            "when": {
+              "gate_passed": true,
+              "credentialed_gate": false
+            }
+          }
+        ]
+      },
+      "run_completion": {
+        "action": "auto_approve",
+        "when": {
+          "gate_passed": true,
+          "all_phases_visited": true,
+          "credentialed_gate": false
+        }
       }
     },
     "policies": [