agentxchain 2.144.0 → 2.146.0

package/dashboard/app.js

@@ -15,6 +15,7 @@ import { render as renderCrossRepo } from './components/cross-repo.js';
 import { render as renderDelegations } from './components/delegations.js';
 import { render as renderBlockers } from './components/blockers.js';
 import { render as renderArtifacts } from './components/artifacts.js';
+import { render as renderNotifications } from './components/notifications.js';
 import { render as renderMission } from './components/mission.js';
 import { render as renderChain } from './components/chain.js';
 import { render as renderRunHistory } from './components/run-history.js';
@@ -31,6 +32,7 @@ const VIEWS = {
   delegations: { fetch: ['state', 'history'], render: renderDelegations },
   ledger: { fetch: ['state', 'ledger', 'coordinatorState', 'coordinatorLedger', 'repoDecisionsSummary'], render: renderLedger },
   hooks: { fetch: ['audit', 'annotations', 'coordinatorAudit', 'coordinatorAnnotations'], render: renderHooks },
+  notifications: { fetch: ['notifications'], render: renderNotifications },
   blocked: { fetch: ['state', 'audit', 'coordinatorState', 'coordinatorAudit', 'coordinatorBlockers', 'coordinatorRepoStatusRows', 'gateActions'], render: renderBlocked },
   gate: { fetch: ['state', 'history', 'coordinatorState', 'coordinatorHistory', 'coordinatorBarriers', 'gateActions'], render: renderGate },
   initiative: { fetch: ['coordinatorState', 'coordinatorBarriers', 'barrierLedger', 'coordinatorBlockers', 'coordinatorRepoStatusRows'], render: renderInitiative },
@@ -62,6 +64,7 @@ const API_MAP = {
   coordinatorBlockers: '/api/coordinator/blockers',
   coordinatorRepoStatusRows: '/api/coordinator/repo-status',
   workflowKitArtifacts: '/api/workflow-kit-artifacts',
+  notifications: '/api/notifications',
   missions: '/api/missions',
   plans: '/api/plans',
   chainReports: '/api/chain-reports',

package/dashboard/components/notifications.js

@@ -0,0 +1,127 @@
+function esc(str) {
+  if (str == null) return '';
+  return String(str)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function badge(label, color = 'var(--text-dim)') {
+  return `<span class="badge" style="color:${color};border-color:${color}">${esc(label)}</span>`;
+}
+
+function formatResult(entry) {
+  if (entry?.delivered) return badge('delivered', 'var(--green)');
+  if (entry?.timed_out) return badge('timed out', 'var(--yellow)');
+  return badge('failed', 'var(--red)');
+}
+
+function renderWebhookRow(webhook) {
+  return `<tr>
+    <td class="mono">${esc(webhook.name)}</td>
+    <td>${esc(webhook.timeout_ms)}</td>
+    <td>${esc(webhook.event_count)}</td>
+    <td><span class="mono">${esc((webhook.events || []).join(', '))}</span></td>
+  </tr>`;
+}
+
+function renderAuditRow(entry) {
+  const rowStyle = entry?.delivered ? '' : ' style="border-left:3px solid var(--red)"';
+  const statusCode = entry?.status_code == null ? '—' : String(entry.status_code);
+  const duration = entry?.duration_ms == null ? '—' : `${entry.duration_ms}ms`;
+  return `<tr${rowStyle}>
+    <td class="mono">${esc(entry?.emitted_at || '—')}</td>
+    <td><span class="mono">${esc(entry?.event_type || '—')}</span></td>
+    <td class="mono">${esc(entry?.notification_name || '—')}</td>
+    <td>${formatResult(entry)}</td>
+    <td>${esc(statusCode)}</td>
+    <td>${esc(duration)}</td>
+    <td>${esc(entry?.message || '—')}</td>
+  </tr>`;
+}
+
+export function render({ notifications }) {
+  if (!notifications) {
+    return `<div class="placeholder"><h2>Notifications</h2><p>No notification data available.</p></div>`;
+  }
+
+  if (notifications.ok === false) {
+    const hint = notifications.code === 'config_missing'
+      ? ' Run <code>agentxchain init --governed</code> to get started.'
+      : '';
+    return `<div class="placeholder"><h2>Notifications</h2><p>${esc(notifications.error || 'Failed to load notification data.')}${hint}</p></div>`;
+  }
+
+  const recent = Array.isArray(notifications.recent) ? notifications.recent : [];
+  const webhooks = Array.isArray(notifications.webhooks) ? notifications.webhooks : [];
+  const summary = notifications.summary || {};
+
+  if (!notifications.configured && recent.length === 0) {
+    return `<div class="placeholder"><h2>Notifications</h2><p>No <code>notifications.webhooks</code> are configured and no delivery audit entries exist yet.</p></div>`;
+  }
+
+  let html = `<div class="notifications-view"><div class="run-header"><div class="run-meta">`;
+  html += notifications.configured
+    ? badge(`${webhooks.length} webhook${webhooks.length === 1 ? '' : 's'} configured`, 'var(--green)')
+    : badge('not currently configured', 'var(--yellow)');
+  html += badge(`${summary.total_attempts || 0} attempts`, 'var(--accent)');
+  if ((summary.failed || 0) > 0) {
+    html += badge(`${summary.failed} failed`, 'var(--red)');
+  }
+  if ((summary.timed_out || 0) > 0) {
+    html += badge(`${summary.timed_out} timed out`, 'var(--yellow)');
+  }
+  if (notifications.approval_sla?.enabled) {
+    html += badge(`approval SLA: ${(notifications.approval_sla.reminder_after_seconds || []).join(', ')}s`, 'var(--accent)');
+  }
+  html += `</div></div>`;
+
+  if (webhooks.length > 0) {
+    html += `<div class="section"><h3>Notification Targets</h3>
+      <table class="data-table">
+        <thead>
+          <tr>
+            <th>Name</th>
+            <th>Timeout</th>
+            <th>Events</th>
+            <th>Subscribed Event Types</th>
+          </tr>
+        </thead>
+        <tbody>${webhooks.map(renderWebhookRow).join('')}</tbody>
+      </table>
+    </div>`;
+  }
+
+  html += `<div class="section"><h3>Delivery Summary</h3>
+    <p><strong>Delivered:</strong> ${esc(summary.delivered || 0)}<br>
+    <strong>Failed:</strong> ${esc(summary.failed || 0)}<br>
+    <strong>Last emitted:</strong> ${esc(summary.last_emitted_at || '—')}<br>
+    <strong>Last failure:</strong> ${esc(summary.last_failure_at || '—')}</p>
+  </div>`;
+
+  if (recent.length === 0) {
+    html += `<div class="section"><h3>Recent Delivery Attempts</h3><p style="color:var(--text-dim)">No notification deliveries recorded yet.</p></div>`;
+  } else {
+    html += `<div class="section"><h3>Recent Delivery Attempts</h3>
+      <table class="data-table">
+        <thead>
+          <tr>
+            <th>Emitted</th>
+            <th>Event</th>
+            <th>Target</th>
+            <th>Result</th>
+            <th>Status</th>
+            <th>Duration</th>
+            <th>Message</th>
+          </tr>
+        </thead>
+        <tbody>${recent.map(renderAuditRow).join('')}</tbody>
+      </table>
+    </div>`;
+  }
+
+  html += `</div>`;
+  return html;
+}

package/dashboard/index.html

@@ -401,6 +401,7 @@
     <a href="#delegations">Delegations</a>
     <a href="#ledger">Decisions</a>
     <a href="#hooks">Hooks</a>
+    <a href="#notifications">Notifications</a>
     <a href="#blocked">Blocked</a>
     <a href="#gate">Gates</a>
     <a href="#blockers">Blockers</a>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "2.144.0",
+  "version": "2.146.0",
   "description": "CLI for AgentXchain — governed multi-agent software delivery",
   "type": "module",
   "bin": {

package/scripts/release-bump.sh

@@ -69,6 +69,8 @@ echo "AgentXchain Release Identity: ${TARGET_VERSION}"
 echo "============================================="
 
 TARGET_RELEASE_DOC="website-v2/docs/releases/v${TARGET_VERSION//./-}.mdx"
+CURRENT_VERSION=$(node -e "console.log(JSON.parse(require('fs').readFileSync('package.json','utf8')).version)")
+REENTRY_MODE=0
 ALLOWED_RELEASE_PATHS=(
   "cli/CHANGELOG.md"
   "${TARGET_RELEASE_DOC}"
@@ -89,6 +91,10 @@ ALLOWED_RELEASE_PATHS=(
   "cli/homebrew/agentxchain.rb"
   "cli/homebrew/README.md"
 )
+ALLOWED_REENTRY_VERSION_PATHS=(
+  "cli/package.json"
+  "cli/package-lock.json"
+)
 
 is_allowed_release_path() {
   local candidate="$1"
@@ -112,15 +118,32 @@ stage_if_present() {
   fi
 }
 
-# 1. Assert only allowed release-surface dirt is present
-echo "[1/8] Checking release-prep tree state..."
+# 1. Detect version/re-entry state before validating the tree
+echo "[1/10] Checking current version..."
+if [[ "$CURRENT_VERSION" == "$TARGET_VERSION" ]]; then
+  REENTRY_MODE=1
+  echo "  OK: package.json already targets ${TARGET_VERSION}; entering release re-entry mode"
+else
+  echo "  OK: current version is ${CURRENT_VERSION}, bumping to ${TARGET_VERSION}"
+fi
+
+# 2. Assert only allowed release-surface dirt is present
+echo "[2/10] Checking release-prep tree state..."
 DISALLOWED_DIRTY=()
 while IFS= read -r status_line; do
   [[ -z "$status_line" ]] && continue
   path="${status_line#?? }"
-  if ! is_allowed_release_path "$path"; then
-    DISALLOWED_DIRTY+=("$path")
+  if is_allowed_release_path "$path"; then
+    continue
+  fi
+  if [[ "$REENTRY_MODE" -eq 1 ]]; then
+    for allowed in "${ALLOWED_REENTRY_VERSION_PATHS[@]}"; do
+      if [[ "$path" == "$allowed" ]]; then
+        continue 2
+      fi
+    done
   fi
+  DISALLOWED_DIRTY+=("$path")
 done < <(git -C "$REPO_ROOT" status --porcelain)
 
 if [[ "${#DISALLOWED_DIRTY[@]}" -gt 0 ]]; then
@@ -130,17 +153,8 @@ if [[ "${#DISALLOWED_DIRTY[@]}" -gt 0 ]]; then
 fi
 echo "  OK: tree contains only allowed release-prep changes"
 
-# 2. Assert not already at target version
-echo "[2/8] Checking current version..."
-CURRENT_VERSION=$(node -e "console.log(JSON.parse(require('fs').readFileSync('package.json','utf8')).version)")
-if [[ "$CURRENT_VERSION" == "$TARGET_VERSION" ]]; then
-  echo "FAIL: package.json is already at ${TARGET_VERSION}. Cannot double-bump." >&2
-  exit 1
-fi
-echo "  OK: current version is ${CURRENT_VERSION}, bumping to ${TARGET_VERSION}"
-
 # 3. Assert tag does not already exist
-echo "[3/8] Checking for existing tag..."
+echo "[3/10] Checking for existing tag..."
 if git rev-parse "v${TARGET_VERSION}" >/dev/null 2>&1; then
   echo "FAIL: tag v${TARGET_VERSION} already exists. Delete it first or choose a different version." >&2
   exit 1
@@ -236,7 +250,11 @@ fi
 
 # 7. Update version files (no git operations)
 echo "[7/10] Updating version files..."
-npm version "$TARGET_VERSION" --no-git-tag-version
+if [[ "$REENTRY_MODE" -eq 1 ]]; then
+  npm version "$TARGET_VERSION" --no-git-tag-version --allow-same-version
+else
+  npm version "$TARGET_VERSION" --no-git-tag-version
+fi
 echo "  OK: package.json updated to ${TARGET_VERSION}"
 
 # 8. Stage version files
@@ -251,23 +269,58 @@ done
 git -C "$REPO_ROOT" add -- website-v2/docs/releases
 echo "  OK: version files and allowed release surfaces staged"
 
-# 9. Create release commit
-echo "[9/10] Creating release commit..."
-git commit -m "${TARGET_VERSION}
+# 9. Create or reuse release commit
+if git diff --cached --quiet --exit-code; then
+  CURRENT_HEAD_SHA=$(git rev-parse HEAD)
+  echo "[9/10] Resolving re-entry release identity..."
+  COMMIT_MSG=$(git log -1 --format=%s)
+  if [[ "$COMMIT_MSG" == "$TARGET_VERSION" ]]; then
+    COMMIT_BODY=$(git log -1 --format=%B)
+    if [[ "$COMMIT_BODY" != *"Co-Authored-By: ${COAUTHORED_BY}"* ]]; then
+      echo "FAIL: existing HEAD commit for re-entry is missing the required Co-Authored-By trailer" >&2
+      exit 1
+    fi
+    RELEASE_SHA=$(git rev-parse HEAD)
+    echo "  OK: reusing existing release commit ${RELEASE_SHA:0:7}"
+  elif [[ "$REENTRY_MODE" -eq 1 ]]; then
+    echo "  No staged release-surface deltas remain; creating metadata-only release identity commit for ${CURRENT_HEAD_SHA:0:7}"
+    git commit --allow-empty -m "${TARGET_VERSION}
+
+Release-Base: ${CURRENT_HEAD_SHA}
+Co-Authored-By: ${COAUTHORED_BY}"
+    RELEASE_SHA=$(git rev-parse HEAD)
+    COMMIT_BODY=$(git log -1 --format=%B)
+    if [[ "$COMMIT_BODY" != *"Release-Base: ${CURRENT_HEAD_SHA}"* ]]; then
+      echo "FAIL: metadata-only release identity commit is missing the required Release-Base line" >&2
+      exit 1
+    fi
+    if [[ "$COMMIT_BODY" != *"Co-Authored-By: ${COAUTHORED_BY}"* ]]; then
+      echo "FAIL: metadata-only release identity commit is missing the required Co-Authored-By trailer" >&2
+      exit 1
+    fi
+    echo "  OK: metadata-only release identity commit ${RELEASE_SHA:0:7} recorded base ${CURRENT_HEAD_SHA:0:7}"
+  else
+    echo "FAIL: no staged release-identity changes remain, and HEAD is not already the ${TARGET_VERSION} release commit. Found commit message '${COMMIT_MSG}'." >&2
+    exit 1
+  fi
+else
+  echo "[9/10] Creating release commit..."
+  git commit -m "${TARGET_VERSION}
 
 Co-Authored-By: ${COAUTHORED_BY}"
-RELEASE_SHA=$(git rev-parse HEAD)
-COMMIT_MSG=$(git log -1 --format=%s)
-if [[ "$COMMIT_MSG" != "$TARGET_VERSION" ]]; then
-  echo "FAIL: commit message is '${COMMIT_MSG}', expected '${TARGET_VERSION}'" >&2
-  exit 1
-fi
-COMMIT_BODY=$(git log -1 --format=%B)
-if [[ "$COMMIT_BODY" != *"Co-Authored-By: ${COAUTHORED_BY}"* ]]; then
-  echo "FAIL: release commit body is missing the required Co-Authored-By trailer" >&2
-  exit 1
+  RELEASE_SHA=$(git rev-parse HEAD)
+  COMMIT_MSG=$(git log -1 --format=%s)
+  if [[ "$COMMIT_MSG" != "$TARGET_VERSION" ]]; then
+    echo "FAIL: commit message is '${COMMIT_MSG}', expected '${TARGET_VERSION}'" >&2
+    exit 1
+  fi
+  COMMIT_BODY=$(git log -1 --format=%B)
+  if [[ "$COMMIT_BODY" != *"Co-Authored-By: ${COAUTHORED_BY}"* ]]; then
+    echo "FAIL: release commit body is missing the required Co-Authored-By trailer" >&2
+    exit 1
+  fi
+  echo "  OK: commit ${RELEASE_SHA:0:7} with message '${TARGET_VERSION}'"
 fi
-echo "  OK: commit ${RELEASE_SHA:0:7} with message '${TARGET_VERSION}'"
 
 # 9.5. Inline preflight gate — tests, pack, and docs build must pass before tag
 if [[ "$SKIP_PREFLIGHT" -eq 1 ]]; then

package/scripts/release-downstream-truth.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # Release downstream truth — run after all downstream surfaces are updated.
-# Verifies: GitHub release exists, Homebrew tap SHA and URL match registry tarball.
+# Verifies: GitHub release is published on the expected tag URL, Homebrew tap SHA and URL match registry tarball.
 # Usage: bash scripts/release-downstream-truth.sh --target-version <semver>
 set -uo pipefail
 
@@ -91,22 +91,30 @@ echo "[1/3] GitHub release"
 if ! command -v gh >/dev/null 2>&1; then
   fail "gh CLI not available — cannot verify GitHub release"
 else
-  GH_FOUND=false
+  GH_READY=false
+  EXPECTED_GH_URL="https://github.com/shivamtiwari93/agentXchain.dev/releases/tag/v${TARGET_VERSION}"
   for attempt in $(seq 1 "$RETRY_ATTEMPTS"); do
     GH_TAG="$(gh release view "v${TARGET_VERSION}" --json tagName -q '.tagName' 2>/dev/null || true)"
-    if [[ "$GH_TAG" == "v${TARGET_VERSION}" ]]; then
-      GH_FOUND=true
+    GH_DRAFT="$(gh release view "v${TARGET_VERSION}" --json isDraft -q '.isDraft' 2>/dev/null || true)"
+    GH_URL="$(gh release view "v${TARGET_VERSION}" --json url -q '.url' 2>/dev/null || true)"
+    GH_PUBLISHED_AT="$(gh release view "v${TARGET_VERSION}" --json publishedAt -q '.publishedAt' 2>/dev/null || true)"
+    if [[ "$GH_TAG" == "v${TARGET_VERSION}" ]] \
+      && [[ "$GH_DRAFT" == "false" ]] \
+      && [[ "$GH_URL" == "$EXPECTED_GH_URL" ]] \
+      && [[ -n "$GH_PUBLISHED_AT" ]] \
+      && [[ "$GH_PUBLISHED_AT" != "null" ]]; then
+      GH_READY=true
       break
     fi
     if [[ "$attempt" -lt "$RETRY_ATTEMPTS" ]]; then
-      echo "  INFO: GitHub release not found (attempt ${attempt}/${RETRY_ATTEMPTS}); retrying in ${RETRY_DELAY_SECONDS}s..."
+      echo "  INFO: GitHub release not ready (attempt ${attempt}/${RETRY_ATTEMPTS}); retrying in ${RETRY_DELAY_SECONDS}s..."
       sleep "$RETRY_DELAY_SECONDS"
     fi
   done
-  if $GH_FOUND; then
-    pass "GitHub release v${TARGET_VERSION} exists"
+  if $GH_READY; then
+    pass "GitHub release v${TARGET_VERSION} is published on the tagged release URL"
   else
-    fail "GitHub release v${TARGET_VERSION} not found after ${RETRY_ATTEMPTS} attempts"
+    fail "GitHub release v${TARGET_VERSION} is not fully published (tag=${GH_TAG:-<missing>} draft=${GH_DRAFT:-<missing>} url=${GH_URL:-<missing>} publishedAt=${GH_PUBLISHED_AT:-<missing>})"
   fi
 fi
 

package/src/commands/init.js

@@ -103,6 +103,68 @@ const DEFAULT_GOVERNED_LOCAL_DEV_RUNTIME = Object.freeze({
   prompt_transport: 'stdin',
 });
 
+const GOVERNED_GITIGNORE_LINES = Object.freeze([
+  '.env',
+  '.agentxchain/staging/',
+  '.agentxchain/dispatch/',
+  '.agentxchain/transactions/',
+  '.agentxchain/state.json',
+  '.agentxchain/session.json',
+  '.agentxchain/history.jsonl',
+  '.agentxchain/decision-ledger.jsonl',
+  '.agentxchain/repo-decisions.jsonl',
+  '.agentxchain/lock.json',
+  '.agentxchain/hook-audit.jsonl',
+  '.agentxchain/hook-annotations.jsonl',
+  '.agentxchain/run-history.jsonl',
+  '.agentxchain/events.jsonl',
+  '.agentxchain/notification-audit.jsonl',
+  '.agentxchain/schedule-state.json',
+  '.agentxchain/schedule-daemon.json',
+  '.agentxchain/continuous-session.json',
+  '.agentxchain/human-escalations.jsonl',
+  '.agentxchain/sla-reminders.json',
+  '.agentxchain/SESSION_RECOVERY.md',
+  '.agentxchain/migration-report.md',
+  '.agentxchain/intake/',
+  '.agentxchain/missions/',
+  '.agentxchain/multirepo/',
+  '.agentxchain/reviews/',
+  '.agentxchain/reports/',
+  '.agentxchain/proposed/',
+  'TALK.md',
+  'HUMAN_TASKS.md',
+]);
+
+const GOVERNED_GITIGNORE_CONTENT = [
+  '# AgentXchain — secrets',
+  '.env',
+  '',
+  '# AgentXchain — transient execution artifacts (never commit)',
+  '.agentxchain/staging/',
+  '.agentxchain/dispatch/',
+  '.agentxchain/transactions/',
+  '',
+  '# AgentXchain — framework-owned state (gitignored by default in fresh scaffolds)',
+  '# These files remain durable on disk and in export/restore, but defaulting them',
+  '# out of raw `git status` reduces operator noise. Existing tracked copies still',
+  '# appear dirty until the repo explicitly untracks them.',
+  ...GOVERNED_GITIGNORE_LINES.slice(4),
+].join('\n') + '\n';
+
+function ensureGitignoreEntries(gitignorePath, content, requiredEntries) {
+  if (!existsSync(gitignorePath)) {
+    writeFileSync(gitignorePath, content);
+    return;
+  }
+  const existingIgnore = readFileSync(gitignorePath, 'utf8');
+  const existingLines = new Set(existingIgnore.split(/\r?\n/));
+  const missing = requiredEntries.filter(entry => !existingLines.has(entry));
+  if (missing.length === 0) return;
+  const prefix = existingIgnore.endsWith('\n') || existingIgnore.length === 0 ? '' : '\n';
+  writeFileSync(gitignorePath, existingIgnore + prefix + missing.join('\n') + '\n');
+}
+
 const GOVERNED_RUNTIMES = {
   'manual-pm': { type: 'manual' },
   'manual-dev': { type: 'manual' },
@@ -833,28 +895,10 @@ export function scaffoldGoverned(dir, projectName, projectId, templateId = 'gene
   // TALK.md
   writeFileSync(join(dir, 'TALK.md'), `# ${projectName} — Team Talk File\n\nCanonical human-readable handoff log for all agents.\n\n---\n\n`);
 
-  // .gitignore additions with inline comments so operators know what to commit vs. ignore
+  // .gitignore additions with inline comments so fresh governed repos keep
+  // framework-owned runtime state out of raw git status by default.
   const gitignorePath = join(dir, '.gitignore');
-  const gitignoreContent = [
-    '# AgentXchain — secrets',
-    '.env',
-    '',
-    '# AgentXchain — transient execution artifacts (never commit)',
-    '.agentxchain/staging/',
-    '.agentxchain/dispatch/',
-    '.agentxchain/transactions/',
-  ].join('\n') + '\n';
-  const requiredPaths = ['.env', '.agentxchain/staging/', '.agentxchain/dispatch/', '.agentxchain/transactions/'];
-  if (!existsSync(gitignorePath)) {
-    writeFileSync(gitignorePath, gitignoreContent);
-  } else {
-    const existingIgnore = readFileSync(gitignorePath, 'utf8');
-    const missing = requiredPaths.filter(entry => !existingIgnore.split(/\r?\n/).includes(entry));
-    if (missing.length > 0) {
-      const prefix = existingIgnore.endsWith('\n') ? '' : '\n';
-      writeFileSync(gitignorePath, existingIgnore + prefix + missing.join('\n') + '\n');
-    }
-  }
+  ensureGitignoreEntries(gitignorePath, GOVERNED_GITIGNORE_CONTENT, GOVERNED_GITIGNORE_LINES);
 
   return { config, state, scaffoldWorkflowKitConfig };
 }
@@ -1251,16 +1295,7 @@ export async function initCommand(opts) {
   writeFileSync(join(dir, 'HUMAN_TASKS.md'), '# Human Tasks\n\n(Agents append tasks here when they need human action.)\n');
   const gitignorePath = join(dir, '.gitignore');
   const requiredIgnores = ['.env', '.agentxchain-trigger.json', '.agentxchain-prompts/', '.agentxchain-workspaces/', '.agentxchain-watch.pid', '.agentxchain-autonudge.state'];
-  if (!existsSync(gitignorePath)) {
-    writeFileSync(gitignorePath, requiredIgnores.join('\n') + '\n');
-  } else {
-    const existingIgnore = readFileSync(gitignorePath, 'utf8');
-    const missing = requiredIgnores.filter(entry => !existingIgnore.split(/\r?\n/).includes(entry));
-    if (missing.length > 0) {
-      const prefix = existingIgnore.endsWith('\n') ? '' : '\n';
-      writeFileSync(gitignorePath, existingIgnore + prefix + missing.join('\n') + '\n');
-    }
-  }
+  ensureGitignoreEntries(gitignorePath, requiredIgnores.join('\n') + '\n', requiredIgnores);
 
   // .planning/ structure
   mkdirSync(join(dir, '.planning', 'research'), { recursive: true });

package/src/commands/restart.js

@@ -13,13 +13,16 @@
 import chalk from 'chalk';
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
 import { join, dirname } from 'path';
-import { loadProjectContext } from '../lib/config.js';
+import { loadProjectContext, loadProjectState } from '../lib/config.js';
 import {
   assignGovernedTurn,
   getActiveTurns,
   getActiveTurnCount,
   reactivateGovernedRun,
   detectStateBundleDesync,
+  normalizeGovernedStateShape,
+  reconcileApprovalPausesWithConfig,
+  reconcileRecoveryActionsWithConfig,
   STATE_PATH,
   HISTORY_PATH,
   LEDGER_PATH,
@@ -27,7 +30,6 @@ import {
 import { writeDispatchBundle } from '../lib/dispatch-bundle.js';
 import { getDispatchTurnDir } from '../lib/turn-paths.js';
 import { consumeNextApprovedIntent } from '../lib/intake.js';
-import { loadProjectState } from '../lib/config.js';
 import { deriveRecoveryDescriptor } from '../lib/blocked-state.js';
 import { deriveRecommendedContinuityAction } from '../lib/continuity-status.js';
 import { readSessionCheckpoint, writeSessionCheckpoint, captureBaselineRef, SESSION_PATH } from '../lib/session-checkpoint.js';
@@ -178,7 +180,20 @@ export async function restartCommand(opts) {
     process.exit(1);
   }
 
-  const state = JSON.parse(readFileSync(statePath, 'utf8'));
+  let state;
+  try {
+    const parsed = JSON.parse(readFileSync(statePath, 'utf8'));
+    const normalized = normalizeGovernedStateShape(parsed);
+    const reconciledApprovals = reconcileApprovalPausesWithConfig(normalized.state, config);
+    const reconciledRecovery = reconcileRecoveryActionsWithConfig(reconciledApprovals.state, config);
+    state = reconciledRecovery.state;
+    if (normalized.changed || reconciledApprovals.changed || reconciledRecovery.changed) {
+      writeFileSync(statePath, JSON.stringify(state, null, 2));
+    }
+  } catch {
+    console.log(chalk.red('No valid governed state.json found.'));
+    process.exit(1);
+  }
 
   // Load checkpoint (optional — restart can work without it, just with less context)
   const checkpoint = readSessionCheckpoint(root);

package/src/commands/resume.js

@@ -40,6 +40,7 @@ import { deriveRecoveryDescriptor } from '../lib/blocked-state.js';
 import { runHooks } from '../lib/hook-runner.js';
 import { summarizeRunProvenance } from '../lib/run-provenance.js';
 import { consumeNextApprovedIntent } from '../lib/intake.js';
+import { reconcileStaleTurns } from '../lib/stale-turn-watchdog.js';
 
 export async function resumeCommand(opts) {
   const context = loadProjectContext();
@@ -75,6 +76,17 @@ export async function resumeCommand(opts) {
     process.exit(1);
   }
 
+  const staleReconciliation = reconcileStaleTurns(root, state, config);
+  state = staleReconciliation.state || state;
+  if (staleReconciliation.ghost_turns.length > 0) {
+    printGhostTurnRecovery(staleReconciliation.ghost_turns);
+    process.exit(1);
+  }
+  if (staleReconciliation.stale_turns.length > 0) {
+    printStaleTurnRecovery(staleReconciliation.stale_turns);
+    process.exit(1);
+  }
+
   // §47: active + turns present → reject (resume assigns new turns, not re-dispatches)
   const activeCount = getActiveTurnCount(state);
   const activeTurns = getActiveTurns(state);
@@ -351,6 +363,32 @@ export async function resumeCommand(opts) {
   printDispatchSummary(state, config);
 }
 
+function printGhostTurnRecovery(ghostTurns) {
+  console.log(chalk.red.bold('Ghost turn detected — subprocess never started.'));
+  console.log('');
+  for (const ghost of ghostTurns) {
+    const secs = Math.floor(ghost.running_ms / 1000);
+    console.log(`  Turn:    ${ghost.turn_id} (${ghost.role})`);
+    console.log(`  Runtime: ${ghost.runtime_id}`);
+    console.log(`  Age:     ${secs}s with no subprocess output`);
+    console.log(`  Recover: ${chalk.cyan(`agentxchain reissue-turn --turn ${ghost.turn_id} --reason ghost`)}`);
+    console.log('');
+  }
+}
+
+function printStaleTurnRecovery(staleTurns) {
+  console.log(chalk.red.bold('Stale turn detected.'));
+  console.log('');
+  for (const stale of staleTurns) {
+    const mins = Math.floor(stale.running_ms / 60000);
+    console.log(`  Turn:    ${stale.turn_id} (${stale.role})`);
+    console.log(`  Runtime: ${stale.runtime_id}`);
+    console.log(`  Age:     ${mins}m with no output`);
+    console.log(`  Recover: ${chalk.cyan(`agentxchain reissue-turn --turn ${stale.turn_id} --reason stale`)}`);
+    console.log('');
+  }
+}
+
 // ── Helpers ─────────────────────────────────────────────────────────────────
 
 function printResumeRunContext({ root, state, config }) {