@jaimevalasek/aioson 1.33.1 → 1.37.0

package/src/commands/live.js

@@ -235,14 +235,30 @@ async function resolveExecutablePath(command) {
     .map((entry) => entry.trim())
     .filter(Boolean);
 
-  const extensions = process.platform === 'win32'
-    ? Array.from(new Set([...String(process.env.PATHEXT || '.EXE;.CMD;.BAT;.COM').split(';').map((entry) => entry.toLowerCase())]))
-    : [''];
+  // No Windows NUNCA testamos o arquivo sem extensão: o npm instala um shim
+  // extensionless (script sh) ao lado do .cmd, e ele não é executável via
+  // CreateProcess — spawná-lo dá ENOENT mesmo com o arquivo existindo.
+  // filter(Boolean) descarta segmentos vazios de um PATHEXT malformado
+  // (";.COM;..."), que viravam candidato sem extensão.
+  let extensions;
+  if (process.platform === 'win32') {
+    extensions = Array.from(new Set(
+      String(process.env.PATHEXT || '.EXE;.CMD;.BAT;.COM')
+        .split(';')
+        .map((entry) => entry.trim().toLowerCase())
+        .filter(Boolean)
+    ));
+    if (extensions.length === 0) {
+      extensions = ['.exe', '.cmd', '.bat', '.com'];
+    }
+  } else {
+    extensions = [''];
+  }
 
   for (const dir of pathEntries) {
     for (const ext of extensions) {
-      const candidate = process.platform === 'win32' && ext && !binary.toLowerCase().endsWith(ext)
-        ? path.join(dir, `${binary}${ext}`)
+      const candidate = process.platform === 'win32'
+        ? (binary.toLowerCase().endsWith(ext) ? path.join(dir, binary) : path.join(dir, `${binary}${ext}`))
         : path.join(dir, binary);
       if (await exists(candidate)) {
         return candidate;
@@ -262,6 +278,24 @@ function spawnExecutable(binaryPath) {
   return process.platform === 'win32' ? `"${binaryPath}"` : binaryPath;
 }
 
+function isWindowsPidAlive(pid) {
+  // process.kill(pid, 0) is not authoritative on Windows: it throws EPERM both
+  // for "process exists but no access" AND (commonly) for PIDs that are already
+  // gone. Probe the real process table so a dead PID reconciles instead of
+  // looking 'unknown' forever (which blocks live:start with "session already
+  // active"). Returns true/false when known, null when the probe itself failed.
+  try {
+    const out = require('node:child_process').execFileSync(
+      'tasklist',
+      ['/FI', `PID eq ${pid}`, '/NH', '/FO', 'CSV'],
+      { encoding: 'utf8', windowsHide: true, timeout: 3000 }
+    );
+    return out.includes(`"${pid}"`);
+  } catch {
+    return null;
+  }
+}
+
 function detectProcessState(pid) {
   if (!pid) return 'not_tracked';
   try {
@@ -271,6 +305,12 @@ function detectProcessState(pid) {
     if (error && error.code === 'ESRCH') {
       return 'dead';
     }
+    if (process.platform === 'win32') {
+      const alive = isWindowsPidAlive(Number(pid));
+      if (alive === true) return 'alive';
+      if (alive === false) return 'dead';
+      // probe inconclusive → fall through to 'unknown'
+    }
     return 'unknown';
   }
 }
@@ -649,10 +689,30 @@ function createLiveEventRecord(context, options = {}) {
   };
 }
 
+// Latch de spawn: entre o spawn() e o await de waitForChild existem awaits
+// (writeLiveState etc.). Se o spawn falhar nessa janela, o 'error' emitia sem
+// listener e DERRUBAVA o node ("Unhandled 'error' event"). Guardamos o
+// desfecho no próprio child pra waitForChild resolver/rejeitar mesmo quando o
+// evento já passou.
+function trackChild(child) {
+  child.aiosonSpawnError = null;
+  child.aiosonExit = null;
+  child.on('error', (err) => {
+    if (!child.aiosonSpawnError) child.aiosonSpawnError = err;
+  });
+  child.on('close', (code, signal) => {
+    child.aiosonExit = { code: Number(code || 0), signal: signal || null };
+  });
+  return child;
+}
+
 function waitForChild(child) {
   return new Promise((resolve, reject) => {
+    if (child.aiosonSpawnError) return reject(child.aiosonSpawnError);
+    if (child.aiosonExit) return resolve(child.aiosonExit);
     child.once('error', reject);
     child.once('close', (code, signal) => {
+      if (child.aiosonSpawnError) return reject(child.aiosonSpawnError);
       resolve({ code: Number(code || 0), signal: signal || null });
     });
   });
@@ -1295,12 +1355,12 @@ async function runLiveStart({ args, options = {}, logger, t }) {
           let attachResult = null;
 
           if (attach && !noLaunch) {
-            attachChild = spawn(spawnExecutable(binaryPath), buildLaunchArgs(options, tool), {
+            attachChild = trackChild(spawn(spawnExecutable(binaryPath), buildLaunchArgs(options, tool), {
               cwd: targetDir,
               env: process.env,
               stdio: 'inherit',
               shell: process.platform === 'win32'
-            });
+            }));
             state.child_pid = attachChild.pid || null;
             if (existing.task?.task_key) {
               const taskMeta = parseTaskMeta(existing.task);
@@ -1404,12 +1464,12 @@ async function runLiveStart({ args, options = {}, logger, t }) {
           });
         } else {
           // Fallback to normal spawn if tmux not available
-          child = spawn(spawnExecutable(binaryPath), buildLaunchArgs(options, tool), {
+          child = trackChild(spawn(spawnExecutable(binaryPath), buildLaunchArgs(options, tool), {
             cwd: targetDir,
             env: process.env,
             stdio: 'inherit',
             shell: process.platform === 'win32'
-          });
+          }));
           taskMeta.child_pid = child.pid || null;
           updateTask(db, {
             taskKey,
@@ -1417,12 +1477,12 @@ async function runLiveStart({ args, options = {}, logger, t }) {
           });
         }
       } else {
-        child = spawn(spawnExecutable(binaryPath), buildLaunchArgs(options, tool), {
+        child = trackChild(spawn(spawnExecutable(binaryPath), buildLaunchArgs(options, tool), {
           cwd: targetDir,
           env: process.env,
           stdio: 'inherit',
           shell: process.platform === 'win32'
-        });
+        }));
         taskMeta.child_pid = child.pid || null;
         updateTask(db, {
           taskKey,

package/src/commands/review-feature.js

@@ -0,0 +1,189 @@
+'use strict';
+
+/**
+ * aioson review:feature [path] [--feature=<slug>] [--scope=<target>]
+ *   [--skip-audit] [--out-dir=<dir>] [--tool=<tool>] [--json]
+ *
+ * One-shot "review an already-implemented feature" helper. It does NOT replace
+ * the workflow gates — it is the post-close / standalone path for re-running the
+ * adversarial + test passes against a feature:
+ *
+ *   1. runs the deterministic `security:audit` for the slug (writes/refreshes
+ *      security-findings-{slug}.json),
+ *   2. prepares the `@pentester` and `@tester` activation prompts (read-only,
+ *      headless — no runtime session, no state mutation),
+ *   3. prints a copy-pasteable plan (or saves the prompts to files / emits JSON).
+ *
+ * Slug resolution: explicit `--feature`/`--slug` wins; otherwise the active
+ * feature (pulse / unique in_progress). After `feature:close` there is no active
+ * feature, so the caller must pass `--feature` — the command says so explicitly.
+ */
+
+const path = require('node:path');
+const fs = require('node:fs');
+
+const { runSecurityAudit } = require('./security-audit');
+const { runAgentPrompt } = require('./agents');
+const { resolveActiveFeature } = require('./feature-current');
+
+function silentLogger() {
+  return { log() {}, error() {} };
+}
+
+// Build an agent activation prompt without side effects (headless skips workflow
+// routing, runtime bootstrap and telemetry). Returns the prompt string, or an
+// `{ error }` object when the prompt could not be built.
+async function buildAgentPromptText(agentName, targetDir, agentOptions, t) {
+  try {
+    const res = await runAgentPrompt({
+      args: [agentName, targetDir],
+      options: { ...agentOptions, headless: true },
+      logger: silentLogger(),
+      t
+    });
+    return res && res.ok && typeof res.prompt === 'string' ? res.prompt : { error: 'prompt_unavailable' };
+  } catch (err) {
+    return { error: err.message };
+  }
+}
+
+async function runReviewFeature({ args, options = {}, logger, t }) {
+  const targetDir = path.resolve(process.cwd(), args?.[0] || '.');
+  const tool = options.tool || 'claude';
+
+  // 1. Resolve the feature slug.
+  let slug = String(options.feature || options.slug || '').trim();
+  let slugSource = slug ? 'explicit' : null;
+  if (!slug) {
+    const active = await resolveActiveFeature(targetDir);
+    if (active.ambiguous) {
+      const msg = `review:feature: ${active.candidates.length} features are in_progress (${active.candidates.join(', ')}). Pass --feature=<slug>.`;
+      if (options.json) return { ok: false, reason: 'ambiguous_feature', candidates: active.candidates };
+      logger.error(msg);
+      return { ok: false, reason: 'ambiguous_feature' };
+    }
+    if (!active.slug) {
+      const msg = 'review:feature: no active feature found — pass --feature=<slug> (a closed feature is no longer the active one).';
+      if (options.json) return { ok: false, reason: 'missing_feature' };
+      logger.error(msg);
+      return { ok: false, reason: 'missing_feature' };
+    }
+    slug = active.slug;
+    slugSource = active.source;
+  }
+
+  // 2. Deterministic security audit (non-fatal — the review still produces the
+  //    agent prompts even when the audit cannot run, e.g. archived artifacts).
+  let audit = null;
+  const skipAudit = Boolean(options['skip-audit'] || options.skipAudit);
+  if (!skipAudit) {
+    // security:audit sets process.exitCode by finding severity. review:feature
+    // is a prep/report command — surfacing findings is its job, not a failure —
+    // so capture the audit's verdict in the result but do not let it set this
+    // command's exit code.
+    const prevExitCode = process.exitCode;
+    audit = await runSecurityAudit({
+      args: [targetDir],
+      options: { feature: slug, json: true, ...(options.now ? { now: options.now } : {}) },
+      logger: silentLogger()
+    });
+    process.exitCode = prevExitCode;
+  }
+
+  // 3. Prepare the @pentester + @tester prompts.
+  const scope = String(options.scope || '').trim();
+  const pentesterPrompt = await buildAgentPromptText('pentester', targetDir, {
+    tool,
+    feature: slug,
+    ...(scope ? { mode: 'app_target', scope } : {})
+  }, t);
+  const testerPrompt = await buildAgentPromptText('tester', targetDir, { tool, feature: slug }, t);
+
+  // optional: persist the prompts to files
+  const outDirOpt = options['out-dir'] || options.outDir;
+  const saved = {};
+  if (outDirOpt) {
+    const dir = path.resolve(targetDir, String(outDirOpt));
+    fs.mkdirSync(dir, { recursive: true });
+    if (typeof pentesterPrompt === 'string') {
+      const p = path.join(dir, `review-pentester-${slug}.prompt.md`);
+      fs.writeFileSync(p, pentesterPrompt, 'utf8');
+      saved.pentester = p;
+    }
+    if (typeof testerPrompt === 'string') {
+      const p = path.join(dir, `review-tester-${slug}.prompt.md`);
+      fs.writeFileSync(p, testerPrompt, 'utf8');
+      saved.tester = p;
+    }
+  }
+
+  const result = {
+    ok: true,
+    slug,
+    slug_source: slugSource,
+    audit: audit
+      ? {
+          ok: audit.ok,
+          exitCode: audit.exitCode,
+          classification: audit.classification || null,
+          summary: audit.summary || null,
+          findingsCount: audit.findingsCount ?? null,
+          artifactPath: audit.artifactPath || null,
+          reason: audit.reason || null
+        }
+      : null,
+    prompts: {
+      pentester: typeof pentesterPrompt === 'string' ? pentesterPrompt : null,
+      tester: typeof testerPrompt === 'string' ? testerPrompt : null
+    },
+    prompt_errors: {
+      pentester: pentesterPrompt && pentesterPrompt.error ? pentesterPrompt.error : null,
+      tester: testerPrompt && testerPrompt.error ? testerPrompt.error : null
+    },
+    saved,
+    commands: {
+      pentester: `aioson agent:prompt pentester . --tool=${tool} --mode=app_target --feature=${slug} --scope=<target>`,
+      tester: `aioson agent:prompt tester . --tool=${tool} --feature=${slug}`
+    }
+  };
+
+  if (options.json) return result;
+
+  // ── human output ──
+  const resolvedNote = slugSource && slugSource !== 'explicit' ? ` (resolved from ${slugSource})` : '';
+  logger.log(`Review plan — feature: ${slug}${resolvedNote}`);
+  logger.log('');
+
+  if (!skipAudit && audit) {
+    const s = audit.summary;
+    if (s) {
+      logger.log(`1. security:audit (deterministic) — ${audit.classification || '?'}: ${s.critical || 0} critical, ${s.high || 0} high, ${s.medium || 0} medium, ${s.low || 0} low, ${s.inconclusive || 0} inconclusive`);
+      if (audit.artifactPath) logger.log(`   findings → ${path.relative(targetDir, audit.artifactPath)}`);
+    } else {
+      logger.log(`1. security:audit — could not run (${audit.reason || 'unknown'}); proceeding with the agent prompts.`);
+    }
+  } else {
+    logger.log('1. security:audit — skipped (--skip-audit)');
+  }
+  logger.log('');
+
+  logger.log('2. @pentester — adversarial review (vulnerabilities, threat surface):');
+  if (saved.pentester) logger.log(`   saved → ${path.relative(targetDir, saved.pentester)}`);
+  if (!scope) logger.log('   tip: pass --scope=<target> for a precise app_target review contract');
+  logger.log('');
+  logger.log(typeof pentesterPrompt === 'string'
+    ? pentesterPrompt
+    : `   [could not build @pentester prompt: ${pentesterPrompt.error}]`);
+  logger.log('');
+
+  logger.log('3. @tester — engineering test pass (missing tests, regressions):');
+  if (saved.tester) logger.log(`   saved → ${path.relative(targetDir, saved.tester)}`);
+  logger.log('');
+  logger.log(typeof testerPrompt === 'string'
+    ? testerPrompt
+    : `   [could not build @tester prompt: ${testerPrompt.error}]`);
+
+  return result;
+}
+
+module.exports = { runReviewFeature };

package/src/commands/runtime.js

@@ -1171,6 +1171,12 @@ async function runRuntimeLog({ args, options = {}, logger, t }) {
  *
  * Intended to be called ONCE at the very end of an agent session, after delivering the main artifact.
  */
+function logVerifyArtifactLine(logger, va) {
+  if (!va) return;
+  const marker = va.skipped ? 'hint' : va.ok ? 'ok' : 'advisory';
+  logger.log(`agent:done — verify:artifact (${va.kind}): ${marker}${va.reason ? ` — ${va.reason}` : ''}`);
+}
+
 async function runAgentDone({ args, options = {}, logger, t }) {
   const targetDir = resolveTargetDir(args);
   const agentName = String(options.agent || '').trim();
@@ -1187,6 +1193,13 @@ async function runAgentDone({ args, options = {}, logger, t }) {
     ? String(options.artifacts).split(',').map((p) => p.trim()).filter(Boolean)
     : [];
 
+  // Build-free artifact done-gate (advisory): for the peripheral agents that
+  // produce a non-code artifact, prove it is complete/well-formed at the same
+  // session-end call they always make, instead of relying on each agent to run
+  // its `## Done gate` line. Resolved once here; surfaced on every return path.
+  const { verifyAgentArtifact } = require('../artifact-kinds');
+  const verifyArtifact = await verifyAgentArtifact({ targetDir, agent: normalizedAgent, options });
+
   const { db, dbPath, runtimeDir } = await openRuntimeDb(targetDir);
 
   try {
@@ -1224,7 +1237,7 @@ async function runAgentDone({ args, options = {}, logger, t }) {
       }
 
       // F2 (workflow-handoff-integrity v1.9.5) — best-effort auto-advance workflow pointer
-      const autoAdvance = await maybeAutoAdvanceWorkflow({ targetDir, normalizedAgent, options, logger, t });
+      const autoAdvance = await maybeAutoAdvanceWorkflow({ targetDir, normalizedAgent, options, logger, t });
 
       if (isDocCreatingAgent(normalizedAgent)) {
         backupAiosonDocs(targetDir).catch(() => {});
@@ -1252,7 +1265,8 @@ async function runAgentDone({ args, options = {}, logger, t }) {
         });
       } catch { /* ignore — never blocks agent_done */ }
 
-      return { ok: true, targetDir, dbPath, agent: normalizedAgent, mode: 'live_event', runKey: session.runKey, auto_advance: autoAdvance };
+      if (!options.json) logVerifyArtifactLine(logger, verifyArtifact);
+      return { ok: true, targetDir, dbPath, agent: normalizedAgent, mode: 'live_event', runKey: session.runKey, auto_advance: autoAdvance, verify_artifact: verifyArtifact };
     }
 
     // No active session — create a standalone task+run and immediately complete it.
@@ -1297,7 +1311,7 @@ async function runAgentDone({ args, options = {}, logger, t }) {
     }
 
     // F2 (workflow-handoff-integrity v1.9.5) — best-effort auto-advance workflow pointer
-    const autoAdvance = await maybeAutoAdvanceWorkflow({ targetDir, normalizedAgent, options, logger, t });
+    const autoAdvance = await maybeAutoAdvanceWorkflow({ targetDir, normalizedAgent, options, logger, t });
 
     if (isDocCreatingAgent(normalizedAgent)) {
       backupAiosonDocs(targetDir).catch(() => {});
@@ -1325,7 +1339,8 @@ async function runAgentDone({ args, options = {}, logger, t }) {
       });
     } catch { /* ignore — never blocks agent_done */ }
 
-    return { ok: true, targetDir, dbPath, agent: normalizedAgent, mode: 'standalone', runKey, taskKey, auto_advance: autoAdvance };
+    if (!options.json) logVerifyArtifactLine(logger, verifyArtifact);
+    return { ok: true, targetDir, dbPath, agent: normalizedAgent, mode: 'standalone', runKey, taskKey, auto_advance: autoAdvance, verify_artifact: verifyArtifact };
   } finally {
     db.close();
   }
@@ -2026,9 +2041,9 @@ function parseDurationMs(value, defaultHours = 24) {
  *
  * Sources checked:
  *   1. Session files in .aioson/.sessions/ with finished=false older than threshold.
- *   2. agent_runs rows with status='running'/'queued' older than threshold
- *      that have no corresponding live session file (orphaned DB records).
- *   3. workflow tasks/runs left running after a workflow finished or was abandoned.
+ *   2. agent_runs rows with status='running'/'queued' older than threshold
+ *      that have no corresponding live session file (orphaned DB records).
+ *   3. workflow tasks/runs left running after a workflow finished or was abandoned.
  *
  * --older-than  Duration threshold. Accepts: 24h (default), 8h, 30m, 7d.
  * --dry-run     Report what would be recovered without making any changes.
@@ -2109,31 +2124,31 @@ async function runAgentRecover({ args, options = {}, logger }) {
       recovered.push({ source: 'session_file', agent: agentName, runKey, taskKey, startedAt: session.startedAt });
     }
 
-    // ── 2. Scan DB for orphaned running runs (no session file) ────────────────
-    const orphanedRuns = db.prepare(`
-      SELECT run_key, task_key, agent_name, source, started_at
-      FROM agent_runs
-      WHERE status IN ('running', 'queued')
-        AND COALESCE(started_at, updated_at, '') < ?
-    `).all(cutoffIso);
-
-    for (const run of orphanedRuns) {
-      // Skip if already recovered via session file
-      if (recovered.some((r) => r.runKey === run.run_key)) continue;
-      const source = run.source === 'workflow' ? 'workflow_run' : 'orphaned_run';
-      const summary = source === 'workflow_run'
-        ? 'Recovered: stale workflow run left running'
-        : 'Recovered: orphaned run with no session file';
-
-      if (!dryRun) {
-        db.prepare(`
-          UPDATE agent_runs
-          SET status = 'abandoned', summary = ?, updated_at = ?, finished_at = ?
-          WHERE run_key = ?
-        `).run(summary, now, now, run.run_key);
-
-        if (run.task_key) {
-          const taskRow = db.prepare('SELECT task_key, status FROM tasks WHERE task_key = ?').get(run.task_key);
+    // ── 2. Scan DB for orphaned running runs (no session file) ────────────────
+    const orphanedRuns = db.prepare(`
+      SELECT run_key, task_key, agent_name, source, started_at
+      FROM agent_runs
+      WHERE status IN ('running', 'queued')
+        AND COALESCE(started_at, updated_at, '') < ?
+    `).all(cutoffIso);
+
+    for (const run of orphanedRuns) {
+      // Skip if already recovered via session file
+      if (recovered.some((r) => r.runKey === run.run_key)) continue;
+      const source = run.source === 'workflow' ? 'workflow_run' : 'orphaned_run';
+      const summary = source === 'workflow_run'
+        ? 'Recovered: stale workflow run left running'
+        : 'Recovered: orphaned run with no session file';
+
+      if (!dryRun) {
+        db.prepare(`
+          UPDATE agent_runs
+          SET status = 'abandoned', summary = ?, updated_at = ?, finished_at = ?
+          WHERE run_key = ?
+        `).run(summary, now, now, run.run_key);
+
+        if (run.task_key) {
+          const taskRow = db.prepare('SELECT task_key, status FROM tasks WHERE task_key = ?').get(run.task_key);
           if (taskRow && (taskRow.status === 'running' || taskRow.status === 'queued')) {
             db.prepare(`
               UPDATE tasks
@@ -2141,40 +2156,40 @@ async function runAgentRecover({ args, options = {}, logger }) {
               WHERE task_key = ?
             `).run(now, now, run.task_key);
           }
-        }
-      }
-
-      recovered.push({ source, agent: run.agent_name, runKey: run.run_key, taskKey: run.task_key, startedAt: run.started_at });
-    }
-
-    // ── 3. Scan DB for stale workflow tasks without a recovered run ───────────
-    const staleWorkflowTasks = db.prepare(`
-      SELECT task_key, title, created_by, session_key, created_at, updated_at
-      FROM tasks
-      WHERE status IN ('running', 'queued')
-        AND (created_by = '@workflow' OR session_key LIKE 'workflow:%')
-        AND COALESCE(updated_at, created_at, '') < ?
-    `).all(cutoffIso);
-
-    for (const task of staleWorkflowTasks) {
-      if (recovered.some((r) => r.taskKey === task.task_key)) continue;
-
-      if (!dryRun) {
-        db.prepare(`
-          UPDATE tasks
-          SET status = 'abandoned', updated_at = ?, finished_at = ?
-          WHERE task_key = ?
-        `).run(now, now, task.task_key);
-      }
-
-      recovered.push({
-        source: 'workflow_task',
-        agent: task.created_by || '@workflow',
-        runKey: null,
-        taskKey: task.task_key,
-        startedAt: task.updated_at || task.created_at
-      });
-    }
+        }
+      }
+
+      recovered.push({ source, agent: run.agent_name, runKey: run.run_key, taskKey: run.task_key, startedAt: run.started_at });
+    }
+
+    // ── 3. Scan DB for stale workflow tasks without a recovered run ───────────
+    const staleWorkflowTasks = db.prepare(`
+      SELECT task_key, title, created_by, session_key, created_at, updated_at
+      FROM tasks
+      WHERE status IN ('running', 'queued')
+        AND (created_by = '@workflow' OR session_key LIKE 'workflow:%')
+        AND COALESCE(updated_at, created_at, '') < ?
+    `).all(cutoffIso);
+
+    for (const task of staleWorkflowTasks) {
+      if (recovered.some((r) => r.taskKey === task.task_key)) continue;
+
+      if (!dryRun) {
+        db.prepare(`
+          UPDATE tasks
+          SET status = 'abandoned', updated_at = ?, finished_at = ?
+          WHERE task_key = ?
+        `).run(now, now, task.task_key);
+      }
+
+      recovered.push({
+        source: 'workflow_task',
+        agent: task.created_by || '@workflow',
+        runKey: null,
+        taskKey: task.task_key,
+        startedAt: task.updated_at || task.created_at
+      });
+    }
 
     // ── Output ────────────────────────────────────────────────────────────────
     const olderThanLabel = options['older-than'] || options.olderThan || '24h';

package/src/commands/sync-agents-copy.js

@@ -0,0 +1,115 @@
+'use strict';
+
+// Cross-platform replacement for the legacy `rsync -av template/ ./` step in the
+// `sync:agents` npm script. rsync is not available on Windows, which silently
+// left the workspace un-synced. This mirrors template/ into the repo root using
+// Node's fs, replicating the original rsync excludes:
+//   --exclude='config.md' --exclude='runtime/' --exclude='backups/' --exclude='mcp/servers.local.json'
+// rsync matched those names at any depth; we replicate that (basename / dir
+// segment / path suffix).
+//
+// We also exclude the live project-state files (project-pulse.md, project-map.md,
+// learning-loop.json, git-guard.json): the dogfooding workspace owns its own
+// evolving state, so a template sync must never overwrite it with the template
+// seeds. External project installs (`aioson update`) are a separate code path and
+// still receive the seeds.
+//
+// Gateway-pointer files (CLAUDE.md / AGENTS.md / OPENCODE.md) carry an AIOSON
+// managed block (<!-- AIOSON:BEGIN --> … <!-- AIOSON:END -->) when a project was
+// installed/updated. A blind copy of the raw template body STRIPS that block (and
+// any project content around it). So when the destination already has a managed
+// block, we refresh it in place via mergeGatewayPointer (same path the installer
+// uses) instead of clobbering it. When the destination has no block we keep the
+// plain copy — that leaves the framework repo's own raw CLAUDE.md untouched.
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const {
+  isGatewayPointerPath,
+  findBlockRange,
+  mergeGatewayPointer
+} = require('../gateway-pointer-merge');
+
+const EXCLUDE_BASENAMES = new Set([
+  'config.md',
+  // live project-state — owned by the workspace, never clobbered by template seeds
+  'project-pulse.md',
+  'project-map.md',
+  'learning-loop.json',
+  'git-guard.json'
+]);
+const EXCLUDE_DIR_NAMES = new Set(['runtime', 'backups']);
+const EXCLUDE_SUFFIXES = [path.join('mcp', 'servers.local.json')];
+
+// `relPath` is relative to template/ and uses the OS separator.
+function isExcluded(relPath) {
+  const segments = relPath.split(path.sep).filter(Boolean);
+  const base = segments[segments.length - 1];
+  if (EXCLUDE_BASENAMES.has(base)) return true;
+  // a directory named runtime/ or backups/ anywhere in the path (or the dir itself)
+  if (segments.some((seg) => EXCLUDE_DIR_NAMES.has(seg))) return true;
+  if (EXCLUDE_SUFFIXES.some((suf) => relPath === suf || relPath.endsWith(path.sep + suf))) return true;
+  return false;
+}
+
+// Refresh an AIOSON-managed block in place when the destination already has one;
+// otherwise fall back to a plain copy. Keeps markers + any project-authored
+// content around the block intact (the blind copy would have stripped them).
+async function copyGatewayPointer(srcChild, destChild) {
+  await fs.mkdir(path.dirname(destChild), { recursive: true });
+  let hasBlock = false;
+  try {
+    const existing = await fs.readFile(destChild, 'utf8');
+    hasBlock = findBlockRange(existing) !== null;
+  } catch {
+    hasBlock = false; // destination missing/unreadable → plain copy
+  }
+  if (hasBlock) {
+    await mergeGatewayPointer({ templatePath: srcChild, targetPath: destChild });
+  } else {
+    await fs.copyFile(srcChild, destChild);
+  }
+}
+
+async function copyTree(srcRoot, destRoot, relPath = '') {
+  const entries = await fs.readdir(path.join(srcRoot, relPath), { withFileTypes: true });
+  let copied = 0;
+  for (const entry of entries) {
+    const childRel = path.join(relPath, entry.name);
+    if (isExcluded(childRel)) continue;
+    const srcChild = path.join(srcRoot, childRel);
+    const destChild = path.join(destRoot, childRel);
+    if (entry.isDirectory()) {
+      await fs.mkdir(destChild, { recursive: true });
+      copied += await copyTree(srcRoot, destRoot, childRel);
+    } else if (entry.isFile()) {
+      if (isGatewayPointerPath(childRel)) {
+        await copyGatewayPointer(srcChild, destChild);
+      } else {
+        await fs.mkdir(path.dirname(destChild), { recursive: true });
+        await fs.copyFile(srcChild, destChild);
+      }
+      copied += 1;
+    }
+  }
+  return copied;
+}
+
+async function syncAgentsCopy(rootDir = process.cwd()) {
+  const templateDir = path.join(rootDir, 'template');
+  const copied = await copyTree(templateDir, rootDir);
+  return { copied };
+}
+
+module.exports = { syncAgentsCopy, isExcluded };
+
+if (require.main === module) {
+  syncAgentsCopy(process.cwd())
+    .then(({ copied }) => {
+      console.log(`[sync:agents] mirrored template/ -> ./ (${copied} files, cross-platform copy; rsync not required)`);
+    })
+    .catch((err) => {
+      console.error(`[sync:agents] copy failed: ${err.message}`);
+      process.exitCode = 1;
+    });
+}