@geraldmaron/construct 1.4.1 → 1.5.0

package/lib/init-unified.mjs

@@ -26,6 +26,7 @@ import { missingIgnorePatterns, isConstructPackageRepo } from './host-dispositio
 import { HOST_KEYS, displayNameToKey } from './platforms/capabilities.mjs';
 import { DOC_LANES, LANE_ORDER, DOC_PRESETS } from './init/doc-lanes.mjs';
 import { initWorkflow } from './workflow-state.mjs';
+import { isMainModule } from './roots.mjs';
 
 const __dirname = fileURLToPath(new URL(".", import.meta.url));
 const ROOT_DIR = path.join(__dirname, "..");
@@ -45,6 +46,7 @@ const withPostmortemsFlag = args.includes("--with-postmortems");
 const withArchitectureFlag = args.includes("--with-architecture");
 const withReadmeFlag = args.includes("--with-readme");
 const withDevcontainerFlag = args.includes("--devcontainer");
+const withSeedIndexFlag = args.includes("--seed-index");
 
 // Behavior flags
 const verbose = args.includes("--verbose") || args.includes("-v");
@@ -56,6 +58,10 @@ const skipInteractive = !interactive;
 // templates/ already exist (issue #97).
 const forceScaffold = args.includes("--force");
 
+// --no-beads skips tracker initialization entirely and marks beads as disabled
+// in the result. Use when the host environment cannot run bd (e.g. ephemeral CI).
+const noBeads = args.includes("--no-beads");
+
 // `bd init` is git-native and unconditionally commits its bootstrap; ADR-0027
 // §3 requires init to leave the host repo's commit history untouched unless the
 // user opts in. --commit-bootstrap keeps that commit; the default withholds it.
@@ -986,41 +992,49 @@ async function main() {
     skipped.push('.cx/construct_guide.md');
   }
 
-  // Auto-init beads
+  // Auto-init beads. Fail-closed: a tracker failure leaves the project in an
+  // inconsistent state (no hooks, no issue tracking) — better to stop early than
+  // silently proceed. Pass --no-beads to opt out for ephemeral/CI environments.
   const beadsMeta = path.join(target, ".beads", "metadata.json");
-  if (!fs.existsSync(beadsMeta) && !isToolRepo) {
+  let beadsReady = false;
+  if (noBeads) {
+    console.log('  ⚠️  Skipping task tracker initialization (--no-beads).');
+    skipped.push('.beads/ (--no-beads)');
+  } else if (!fs.existsSync(beadsMeta) && !isToolRepo) {
     console.log('');
     console.log('Initializing the task tracker (beads — local-first, git-synced, works offline)…');
     fs.mkdirSync(path.join(target, ".beads"), { recursive: true });
-    try {
-      const beads = initializeBeadsTracker(target, { commitBootstrap });
-      created.push(".beads/ (initialized)");
-      const prefixNote = beads?.prefix ? ` — issues prefixed \`${beads.prefix}-\`` : "";
-      console.log(`  ✓ Task tracker ready${prefixNote}. Run \`bd quickstart\` to start.`);
-      if (beads?.withheldCommit) {
-        console.log("    Bootstrap files left uncommitted (commit them yourself, or re-run with --commit-bootstrap).");
-      }
-    } catch (e) {
-      console.warn("⚠️  Beads init failed:", e.message);
+    const beads = initializeBeadsTracker(target, { commitBootstrap });
+    created.push(".beads/ (initialized)");
+    const prefixNote = beads?.prefix ? ` — issues prefixed \`${beads.prefix}-\`` : "";
+    console.log(`  ✓ Task tracker ready${prefixNote}. Run \`bd quickstart\` to start.`);
+    if (beads?.withheldCommit) {
+      console.log("    Bootstrap files left uncommitted (commit them yourself, or re-run with --commit-bootstrap).");
     }
     console.log('');
+    beadsReady = true;
+  } else if (fs.existsSync(beadsMeta)) {
+    beadsReady = true;
   }
 
   // Wire the project's git hooks to .beads/hooks so Construct's pre-commit
   // secret-scan and policy gates activate. Owned by init, not install (ADR-0027
   // §3): install must never mutate the cwd repo. Idempotent — no-op when
   // .beads/hooks/pre-commit is absent or a non-default custom path is set.
+  // Skipped when beads is disabled or was not successfully initialized.
 
-  try {
-    const { ensureGitHooksPath } = await import('./git-hooks-path.mjs');
-    const hooks = ensureGitHooksPath({ cwd: target });
-    if (hooks.status === 'set') {
-      created.push('git core.hooksPath → .beads/hooks');
-      if (!quiet) console.log(`  ✓ ${hooks.message}`);
-    } else if (hooks.status === 'warning' && !quiet) {
-      console.log(`  ⚠️  ${hooks.message}`);
-    }
-  } catch { /* git-hooks wiring is advisory; init proceeds */ }
+  if (beadsReady) {
+    try {
+      const { ensureGitHooksPath } = await import('./git-hooks-path.mjs');
+      const hooks = ensureGitHooksPath({ cwd: target });
+      if (hooks.status === 'set') {
+        created.push('git core.hooksPath → .beads/hooks');
+        if (!quiet) console.log(`  ✓ ${hooks.message}`);
+      } else if (hooks.status === 'warning' && !quiet) {
+        console.log(`  ⚠️  ${hooks.message}`);
+      }
+    } catch { /* git-hooks wiring is advisory; init proceeds */ }
+  }
 
   // Inject Construct's integration guidance into AGENTS.md and CLAUDE.md as a
   // versioned, hash-stamped marker block (ADR-0027 §2). Runs after bd init so
@@ -1154,22 +1168,25 @@ async function main() {
     }
   }
 
-  // Seed the vector index from the project's existing docs so the agent
-  // can compare new intake against established PRDs/RFCs/ADRs from day
-  // one. Best-effort: skipped silently when Postgres + embedding model
-  // aren't ready yet (DATABASE_URL unset, no ONNX cache). User can re-run
-  // `construct ingest` or `construct init` later to seed manually.
+  // Vector-index seeding (embedding the project's existing docs so the agent
+  // can compare new intake against established PRDs/RFCs/ADRs) is opt-in via
+  // --seed-index (construct-rf26.17): the default init path performs zero
+  // embedding work and never touches LanceDB, so a project that never uses
+  // semantic search never pays for the model cache or the index directory.
+  // `construct ingest` provisions both lazily on first real use.
+
+  if (withSeedIndexFlag) {
+    try {
+      const { syncFileStateToSql } = await import('./storage/sync.mjs');
+      const projectName = path.basename(target);
+      const seed = await syncFileStateToSql(target, { env: process.env, project: projectName });
+      if (seed?.status === 'ok' && (seed.documentsSynced || 0) > 0) {
+        console.log(`\n🔍 Indexed existing project material: ${seed.documentsSynced} doc(s), ${seed.embeddingsSynced || 0} embeddings.`);
+        console.log(`   The agent can now compare new intake (inbox/) against your existing PRDs, ADRs, and notes.`);
+      }
+    } catch { /* silent — corpus seeding is best-effort, not a setup blocker */ }
+  }
 
-  try {
-    const { syncFileStateToSql } = await import('./storage/sync.mjs');
-    const projectName = path.basename(target);
-    const seed = await syncFileStateToSql(target, { env: process.env, project: projectName });
-    if (seed?.status === 'ok' && (seed.documentsSynced || 0) > 0) {
-      console.log(`\n🔍 Indexed existing project material: ${seed.documentsSynced} doc(s), ${seed.embeddingsSynced || 0} embeddings.`);
-      console.log(`   The agent can now compare new intake (inbox/) against your existing PRDs, ADRs, and notes.`);
-    }
-  } catch { /* silent — corpus seeding is best-effort, not a setup blocker */ }
-  
   // ── Devcontainer recipe ────────────────────────────────────────────────
   if (withDevcontainerFlag) {
     const dcDir = path.join(target, '.devcontainer');
@@ -1252,7 +1269,7 @@ async function main() {
   }
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isMainModule(import.meta.url)) {
   main().catch((error) => {
     console.error(`Error: ${error.message}`);
     process.exit(1);

package/lib/init-update.mjs

@@ -21,6 +21,7 @@ import {
   needsConstructGuideUpdate,
   writeConstructGuideProposal,
 } from "./init-update-guide.mjs";
+import { isMainModule } from './roots.mjs';
 
 const args = process.argv.slice(2);
 const dryRun = args.includes("--dry-run");
@@ -226,7 +227,7 @@ async function main() {
   console.log("To replace .cx/construct_guide.md with the shipped template: construct init:update --apply-guide");
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isMainModule(import.meta.url)) {
   main().catch((error) => {
     console.error(`Error: ${error.message}`);
     process.exit(1);

package/lib/install/legacy-global-cleanup.mjs

@@ -62,6 +62,30 @@ function stripClaudeSettings(homeDir, opts) {
   if (changed) writeJson(filePath, settings, { ...opts, label: '~/.claude/settings.json Construct entries' });
 }
 
+// construct-ranh moved Claude Code's MCP write path off ~/.claude/settings.json
+// (never read by the CLI for server definitions) to ~/.claude.json's top-level
+// `mcpServers`. A post-fix install registers MCP servers there, so this must be
+// stripped alongside settings.json for the memory/cass/construct-mcp bridges to
+// be fully removed.
+
+function stripClaudeUserConfig(homeDir, opts) {
+  const filePath = path.join(homeDir, '.claude.json');
+  const config = readJson(filePath);
+  if (!config || typeof config !== 'object') return;
+  if (!config.mcpServers || typeof config.mcpServers !== 'object') return;
+
+  let changed = false;
+  for (const key of CONSTRUCT_MCP_KEYS) {
+    if (key in config.mcpServers) {
+      delete config.mcpServers[key];
+      changed = true;
+    }
+  }
+  if (Object.keys(config.mcpServers).length === 0) delete config.mcpServers;
+
+  if (changed) writeJson(filePath, config, { ...opts, label: '~/.claude.json Construct MCP entries' });
+}
+
 function stripOpenCode(homeDir, opts) {
   const filePath = path.join(homeDir, '.config', 'opencode', 'opencode.json');
   const config = readJson(filePath);
@@ -173,6 +197,7 @@ export function cleanupLegacyGlobalConstruct({ homeDir, dryRun = false } = {}) {
   });
 
   stripClaudeSettings(homeDir, opts);
+  stripClaudeUserConfig(homeDir, opts);
   stripOpenCode(homeDir, opts);
   stripVsCode(homeDir, opts);
   stripCodex(homeDir, opts);

package/lib/install/stage-project.mjs

@@ -11,7 +11,7 @@
  */
 
 import { spawnSync } from 'node:child_process';
-import { existsSync, copyFileSync, writeFileSync, mkdirSync, chmodSync } from 'node:fs';
+import { existsSync, readFileSync, copyFileSync, writeFileSync, mkdirSync, chmodSync } from 'node:fs';
 import path from 'node:path';
 
 export function stageProjectAdapters({ projectRoot, packageRoot, pkgVersion, log, hosts = null }) {
@@ -27,7 +27,7 @@ export function stageProjectAdapters({ projectRoot, packageRoot, pkgVersion, log
 
   if (!existsSync(syncScript)) {
     emit(`sync-specialists.mjs not found at ${syncScript}; skipping adapter sync`);
-    return { staged: true, synced: false };
+    return finishStage({ projectRoot, pkgVersion, synced: false, reason: 'sync-script-missing' });
   }
 
   // A `hosts` array restricts which adapter sets sync writes (construct-4xy6);
@@ -45,9 +45,46 @@ export function stageProjectAdapters({ projectRoot, packageRoot, pkgVersion, log
 
   if (result.status !== 0) {
     emit(`sync failed (exit ${result.status}); project left in a clean state`);
-    return { staged: true, synced: false };
+    return finishStage({ projectRoot, pkgVersion, synced: false, reason: `sync-exit-${result.status}` });
   }
-  return { staged: true, synced: true };
+  return finishStage({ projectRoot, pkgVersion, synced: true, reason: null });
+}
+
+const STAGE_STATE_FILE = 'stage-state.json';
+
+// Record the staging outcome under .construct/ so a half-stage (launcher present,
+// adapters not synced) is detectable and repairable instead of re-derived from
+// filesystem heuristics. The marker write is best-effort — a state-write failure must
+// never turn a successful stage into a reported failure.
+
+function finishStage({ projectRoot, pkgVersion, synced, reason }) {
+  const dotConstruct = path.join(projectRoot, '.construct');
+  try {
+    mkdirSync(dotConstruct, { recursive: true });
+    const state = { staged: true, synced, reason, pkgVersion: pkgVersion ?? null, ts: new Date().toISOString() };
+    writeFileSync(path.join(dotConstruct, STAGE_STATE_FILE), JSON.stringify(state, null, 2) + '\n');
+  } catch { /* marker is advisory */ }
+  return { staged: true, synced };
+}
+
+export function readStageState(projectRoot) {
+  try {
+    return JSON.parse(readFileSync(path.join(projectRoot, '.construct', STAGE_STATE_FILE), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// Re-drive a half-staged project to a synced state. stageProjectAdapters is idempotent,
+// so re-running the sync is the repair; an already-synced project is a no-op.
+
+export function repairStagedProject({ projectRoot, packageRoot, pkgVersion, log, hosts = null }) {
+  const state = readStageState(projectRoot);
+  if (state && state.synced === true) {
+    return { staged: true, synced: true, repaired: false };
+  }
+  const result = stageProjectAdapters({ projectRoot, packageRoot, pkgVersion, log, hosts });
+  return { ...result, repaired: result.synced === true };
 }
 
 function ensureProjectLauncher({ projectRoot, templateDir, pkgVersion }) {

package/lib/intake/daemon.mjs

@@ -6,6 +6,13 @@
  * Packets past their TTL move to `.cx/intake/dead-letter/`; failed
  * classification retries up to the budget then dead-letters with the reason.
  *
+ * Every tick also sweeps the persisted `.cx/intake/pending/` packets
+ * (sweepPendingPackets): a packet whose `intake.sourcePath` is missing from
+ * disk, or whose age exceeds classifyPacket's TTL, moves to
+ * `.cx/intake/dead-letter/` with a `deadLetterReason`. This covers persisted
+ * packets, not just in-flight inbox files, so the TTL/dead-letter contract
+ * above applies to the whole pending queue.
+ *
  * Atomic handoff (ADR-0045 §C): only complete top-level files are enqueued.
  * Dotfiles and the `inbox/.staging/` assembly directory are skipped, so a file
  * a writer is still staging is invisible until it is renamed into `inbox/`.
@@ -14,18 +21,19 @@
  * idle shutdown, heartbeat, killswitch, single-writer lock) applies.
  */
 
-import { readdirSync, statSync, readFileSync, writeFileSync, renameSync, existsSync, mkdirSync } from 'node:fs';
+import { readdirSync, statSync, readFileSync, writeFileSync, renameSync, unlinkSync, existsSync, mkdirSync } from 'node:fs';
 import { join, basename } from 'node:path';
 
 import { createDaemon, classifyPacket } from '../daemons/contract.mjs';
 import { memoryCapMbFor } from '../resources/process-budget.mjs';
+import { resolveStatePath } from '../state-root.mjs';
 
 const KILLSWITCH_ENV = 'CONSTRUCT_INTAKE_DAEMON';
 
 function inboxDir(cwd) { return join(cwd, 'inbox'); }
 function pendingDir(cwd) { return join(cwd, '.cx', 'intake', 'pending'); }
 function deadLetterDir(cwd) { return join(cwd, '.cx', 'intake', 'dead-letter'); }
-function heartbeatPath(cwd) { return join(cwd, '.cx', 'runtime', 'intake-daemon.heartbeat'); }
+function heartbeatPath(cwd) { return resolveStatePath(cwd, 'runtime', 'intake-daemon.heartbeat'); }
 
 function ensureDir(dir) {
   try { mkdirSync(dir, { recursive: true }); } catch { /* ignore */ }
@@ -60,9 +68,55 @@ function listInboxFiles(cwd) {
     .filter((full) => isSizeStable(full));
 }
 
+function pendingPacketFiles(cwd) {
+  const dir = pendingDir(cwd);
+  if (!existsSync(dir)) return [];
+  try { return readdirSync(dir).filter((name) => name.endsWith('.json')); }
+  catch { return []; }
+}
+
+function readPacketFile(cwd, name) {
+  try { return JSON.parse(readFileSync(join(pendingDir(cwd), name), 'utf8')); }
+  catch { return null; }
+}
+
+function packetSourcePath(packet) {
+  return packet?.intake?.sourcePath || packet?.sourcePath || null;
+}
+
+function packetFirstSeenAt(packet) {
+  return packet?.firstSeenAt || packet?.createdAt || null;
+}
+
+// processInboxFile renames its source into a `.<name>.consumed` marker inside
+// pendingDir once a packet is written, so the original sourcePath disappears
+// the moment ingestion succeeds. That disappearance is expected, not an
+// orphan — the sweep must not dead-letter a packet on the very next tick
+// just because its own consumption already moved the source out of the way.
+
+function hasConsumedMarker(cwd, sourcePath) {
+  return existsSync(join(pendingDir(cwd), `.${basename(sourcePath)}.consumed`));
+}
+
+// A pending packet is keyed by the source file it came from, independent of
+// which ingest path wrote it (flat `sourcePath` here, nested
+// `intake.sourcePath` for packets from lib/intake/prepare.mjs). Finding a
+// live match lets re-ingestion refresh in place instead of writing a sibling
+// packet for the same source.
+
+function findExistingPendingBySource(cwd, sourcePath) {
+  for (const name of pendingPacketFiles(cwd)) {
+    const data = readPacketFile(cwd, name);
+    if (data && packetSourcePath(data) === sourcePath) return { name, data };
+  }
+  return null;
+}
+
 /**
  * Process one inbox file: classify, persist packet to pending, remove the
  * inbox source on success, or move to dead-letter on persistent failure.
+ * A file whose sourcePath already has a live pending packet refreshes that
+ * packet in place rather than writing a second one for the same source.
  *
  * Returns one of:
  *   { didWork: true,  route: 'pending'|'dead-letter', packetId }
@@ -76,10 +130,11 @@ export async function processInboxFile(filePath, { cwd, classify, now = () => ne
   try { body = readFileSync(filePath, 'utf8'); }
   catch (err) { return { didWork: false, reason: `read failed: ${err.message}` }; }
 
-  const id = `intake-${now().getTime()}-${Math.random().toString(36).slice(2, 8)}`;
+  const existing = findExistingPendingBySource(cwd, filePath);
+  const id = existing?.data?.id || `intake-${now().getTime()}-${Math.random().toString(36).slice(2, 8)}`;
   const packet = {
     id,
-    firstSeenAt: new Date(statSync(filePath).mtimeMs).toISOString(),
+    firstSeenAt: existing?.data?.firstSeenAt || new Date(statSync(filePath).mtimeMs).toISOString(),
     sourcePath: filePath,
     excerpt: body.slice(0, 500),
     attempts: 0,
@@ -101,13 +156,15 @@ export async function processInboxFile(filePath, { cwd, classify, now = () => ne
     return { didWork: false, reason: `classify failed, will retry: ${err.message}` };
   }
 
-  const packetPath = join(pendingDir(cwd), `${id}.json`);
+  packet.lastSeenAt = now().toISOString();
+  const packetName = existing?.name || `${id}.json`;
+  const packetPath = join(pendingDir(cwd), packetName);
   writeFileSync(packetPath, JSON.stringify(packet, null, 2));
   try {
     const consumedPath = join(pendingDir(cwd), `.${basename(filePath)}.consumed`);
     renameSync(filePath, consumedPath);
   } catch { /* ignore consume failure */ }
-  return { didWork: true, route: 'pending', packetId: id };
+  return { didWork: true, route: 'pending', packetId: id, refreshed: !!existing };
 }
 
 function persistDeadLetter(filePath, packet, reason, cwd) {
@@ -117,6 +174,40 @@ function persistDeadLetter(filePath, packet, reason, cwd) {
   return { didWork: true, route: 'dead-letter', packetId: packet.id, reason };
 }
 
+/**
+ * Sweep persisted `.cx/intake/pending/` packets: one whose source file is
+ * missing from disk, or whose age exceeds classifyPacket's TTL, moves to
+ * `.cx/intake/dead-letter/` with a `deadLetterReason`. Runs every tick
+ * alongside the inbox scan so packets written by any ingest path (not just
+ * processInboxFile) are covered — the daemon's TTL/dead-letter contract
+ * otherwise only reaches packets still in flight through the inbox.
+ *
+ * Returns the list of { id, reason } packets moved.
+ */
+export function sweepPendingPackets(cwd, { now = () => new Date() } = {}) {
+  const swept = [];
+  for (const name of pendingPacketFiles(cwd)) {
+    const packet = readPacketFile(cwd, name);
+    if (!packet) continue;
+
+    const sourcePath = packetSourcePath(packet);
+    const sourceMissing = !!sourcePath && !existsSync(sourcePath) && !hasConsumedMarker(cwd, sourcePath);
+    const decision = classifyPacket({ firstSeenAt: packetFirstSeenAt(packet), attempts: packet.attempts || 0 });
+
+    let reason = null;
+    if (sourceMissing) reason = 'source-missing';
+    else if (decision.route === 'dead-letter') reason = 'ttl-expired';
+    if (!reason) continue;
+
+    ensureDir(deadLetterDir(cwd));
+    const dlPath = join(deadLetterDir(cwd), name);
+    writeFileSync(dlPath, JSON.stringify({ ...packet, deadLetterReason: reason, deadLetteredAt: now().toISOString() }, null, 2));
+    try { unlinkSync(join(pendingDir(cwd), name)); } catch { /* leave the dead-letter copy even if cleanup fails */ }
+    swept.push({ id: packet.id || name.replace(/\.json$/, ''), reason });
+  }
+  return swept;
+}
+
 /**
  * Build a DaemonRunner for the intake daemon. Caller is responsible for
  * calling .run() — typically construct intake daemon start.
@@ -132,9 +223,9 @@ export function buildIntakeDaemon({ cwd = process.cwd(), intervalMs = 60_000, cl
     maxIdleTicks: 6,
     memoryCapMb: memoryCapMbFor('intake', cwd),
     async tick() {
+      const swept = sweepPendingPackets(cwd);
       const files = listInboxFiles(cwd);
-      if (files.length === 0) return { didWork: false };
-      let workedAny = false;
+      let workedAny = swept.length > 0;
       for (const file of files) {
         const result = await processInboxFile(file, { cwd, classify: classifyFn });
         if (result.didWork) workedAny = true;

package/lib/intake/git-queue.mjs

@@ -4,6 +4,18 @@
  * Backs team/enterprise modes with the filesystem and Git for state
  * synchronization and conflict resolution, with no central database server.
  *
+ * git-queue is the zero-dependency DEFAULT kind:'queue' provider
+ * (construct-9oi4.7.11); substrate owns the queue contract and Postgres is an
+ * optional provider selected through the extension registry.
+ *
+ * Correctness envelope: single-writer-preferred, eventual consistency.
+ * Concurrent claims from multiple agents may result in duplicate claim
+ * attempts; the dolt commit history provides reconciliation. A push failure is
+ * NOT swallowed or ratified as success: claim() returns a typed disposition
+ * ({ durable: false, disposition: 'local-only', reason }) so callers see that
+ * the claim is local-only until the push is confirmed in the dolt remote,
+ * rather than mistaking it for a durable claim.
+ *
  * Structure:
  * .cx/team-inbox/
  *   pending/    - JSON files for unclaimed tasks
@@ -34,9 +46,11 @@ function timestamp() {
 }
 
 export class GitIntakeQueue {
-  constructor({ project, rootDir = process.cwd() } = {}) {
+  constructor({ project, rootDir = process.cwd(), _exec } = {}) {
     this.project = project;
     this.inboxRoot = path.join(rootDir, '.cx', 'team-inbox');
+    // Allow tests to inject a fake exec without monkey-patching the module.
+    this._exec = _exec || execSync;
     this._ensureDirs();
   }
 
@@ -48,8 +62,8 @@ export class GitIntakeQueue {
 
   _gitAddAndCommit(filePath, message) {
     try {
-      execSync(`git add "${filePath}"`, { stdio: 'ignore' });
-      execSync(`git commit -m "${message}"`, { stdio: 'ignore' });
+      this._exec(`git add "${filePath}"`, { stdio: 'ignore' });
+      this._exec(`git commit -m "${message}"`, { stdio: 'ignore' });
     } catch (err) {
       // It's okay if commit fails because of no changes
     }
@@ -93,17 +107,24 @@ export class GitIntakeQueue {
   }
 
   async read(id) {
-    for (const dir of ['pending', 'claimed', 'processed', 'skipped', 'quarantine']) {
-      // Note: 'claimed' has subdirs, we'd need to search recursively for claimed.
-      // For simplicity in this implementation, we assume we know where it is or search pending first.
-      const searchPath = dir === 'claimed' 
-        ? path.join(this.inboxRoot, dir) // needs recursive search
-        : path.join(this.inboxRoot, dir, `${id}.json`);
-      
-      if (dir !== 'claimed' && fs.existsSync(searchPath)) {
+    for (const dir of ['pending', 'processed', 'skipped', 'quarantine']) {
+      const searchPath = path.join(this.inboxRoot, dir, `${id}.json`);
+      if (fs.existsSync(searchPath)) {
         return JSON.parse(fs.readFileSync(searchPath, 'utf8'));
       }
     }
+
+    // 'claimed' uses per-worker subdirectories — search recursively.
+    const claimedBase = path.join(this.inboxRoot, 'claimed');
+    if (fs.existsSync(claimedBase)) {
+      for (const worker of fs.readdirSync(claimedBase)) {
+        const candidate = path.join(claimedBase, worker, `${id}.json`);
+        if (fs.existsSync(candidate)) {
+          return JSON.parse(fs.readFileSync(candidate, 'utf8'));
+        }
+      }
+    }
+
     return null;
   }
 
@@ -111,8 +132,13 @@ export class GitIntakeQueue {
     if (!claimedBy) throw new Error('claim: claimedBy is required');
     
     // Pull latest to minimize conflicts
-
-    try { execSync('git pull --rebase', { stdio: 'ignore' }); } catch (e) {}
+    try {
+      this._exec('git pull --rebase', { stdio: 'ignore' });
+    } catch (pullErr) {
+      // Pull failure is non-fatal — we proceed with local state.
+      // Log a reconciliation record so operators can detect divergence.
+      console.warn(`[git-queue] pull failed before claim (proceeding with local state): ${pullErr.message}`);
+    }
 
     const pendingDir = path.join(this.inboxRoot, 'pending');
     const files = fs.readdirSync(pendingDir).filter(f => f.endsWith('.json')).sort();
@@ -125,31 +151,34 @@ export class GitIntakeQueue {
     fs.mkdirSync(workerDir, { recursive: true });
     const claimedPath = path.join(workerDir, fileName);
 
-    try {
-      // Atomic move on filesystem
-      fs.renameSync(pendingPath, claimedPath);
-      
-      // Update metadata
-      const data = JSON.parse(fs.readFileSync(claimedPath, 'utf8'));
-      data.status = 'claimed';
-      data.claimedBy = claimedBy;
-      data.claimedAt = new Date().toISOString();
-      fs.writeFileSync(claimedPath, JSON.stringify(data, null, 2));
-
-      // Commit and push the claim so peers see it
-
-      execSync(`git add .cx/team-inbox/pending/${fileName} .cx/team-inbox/claimed/${claimedBy}/${fileName}`, { stdio: 'ignore' });
-      execSync(`git commit -m "Claim task ${data.id} by ${claimedBy}"`, { stdio: 'ignore' });
-      execSync('git push', { stdio: 'ignore' });
-
-      return data;
-    } catch (err) {
-      // A push failure means another worker claimed it first or Git is out of
-      // sync; the local move is left for the next 'git pull --rebase' to reconcile.
+    // Atomic move on filesystem
+    fs.renameSync(pendingPath, claimedPath);
+
+    // Update metadata
+    const data = JSON.parse(fs.readFileSync(claimedPath, 'utf8'));
+    data.status = 'claimed';
+    data.claimedBy = claimedBy;
+    data.claimedAt = new Date().toISOString();
+    fs.writeFileSync(claimedPath, JSON.stringify(data, null, 2));
 
-      console.error(`Failed to claim ${fileName}: ${err.message}`);
-      return null;
+    // Commit and push the claim so peers see it. A push failure is reported as a
+    // typed non-durable disposition on the returned claim rather than swallowed:
+    // the local move stands for the next 'git pull --rebase' to reconcile, but
+    // the caller is told the claim is local-only, not durable.
+    data.durable = true;
+    data.disposition = 'pushed';
+    try {
+      this._exec(`git add .cx/team-inbox/pending/${fileName} .cx/team-inbox/claimed/${claimedBy}/${fileName}`, { stdio: 'ignore' });
+      this._exec(`git commit -m "Claim task ${data.id} by ${claimedBy}"`, { stdio: 'ignore' });
+      this._exec('git push', { stdio: 'ignore' });
+    } catch (pushErr) {
+      data.durable = false;
+      data.disposition = 'local-only';
+      data.dispositionReason = pushErr.message;
+      console.warn(`[git-queue] push failed after claim of ${data.id} by ${claimedBy} (claim is local-only until reconciled): ${pushErr.message}`);
     }
+
+    return data;
   }
 
   async markProcessed(id, { processedBy = 'unknown', notes = '' } = {}) {
@@ -187,10 +216,53 @@ export class GitIntakeQueue {
     fs.writeFileSync(processedPath, JSON.stringify(data, null, 2));
 
     this._gitAddAndCommit(this.inboxRoot, `Mark task ${id} as processed`);
-    try { execSync('git push', { stdio: 'ignore' }); } catch (e) {}
+    try { this._exec('git push', { stdio: 'ignore' }); } catch (e) {}
 
     return { id };
   }
 
-  // markSkipped and reopen would follow similar logic...
+  /**
+   * Mark an issue as skipped in local state WITHOUT a push.
+   *
+   * Used for graceful degradation when a push fails or when the caller wants
+   * to skip without touching the remote.  The skip is advisory — it survives
+   * only as a local file move until the next reconciliation pull.
+   *
+   * @param {string} issueId
+   * @returns {{ id: string, skippedAt: string }}
+   */
+  async markSkipped(issueId) {
+    if (!issueId) throw new Error('markSkipped: issueId is required');
+
+    // Locate the file across pending and claimed directories.
+    let foundPath = null;
+
+    const pendingCandidate = path.join(this.inboxRoot, 'pending', `${issueId}.json`);
+    if (fs.existsSync(pendingCandidate)) {
+      foundPath = pendingCandidate;
+    } else {
+      const claimedBase = path.join(this.inboxRoot, 'claimed');
+      if (fs.existsSync(claimedBase)) {
+        for (const worker of fs.readdirSync(claimedBase)) {
+          const candidate = path.join(claimedBase, worker, `${issueId}.json`);
+          if (fs.existsSync(candidate)) { foundPath = candidate; break; }
+        }
+      }
+    }
+
+    if (!foundPath) throw new Error(`markSkipped: no entry ${issueId} found`);
+
+    const data = JSON.parse(fs.readFileSync(foundPath, 'utf8'));
+    data.status = 'skipped';
+    data.skippedAt = new Date().toISOString();
+
+    const skippedPath = path.join(this.inboxRoot, 'skipped', `${issueId}.json`);
+    fs.renameSync(foundPath, skippedPath);
+    fs.writeFileSync(skippedPath, JSON.stringify(data, null, 2));
+
+    // No push — this is a local-only operation (graceful degradation).
+    return { id: issueId, skippedAt: data.skippedAt };
+  }
+
+  // reopen would follow similar logic...
 }

package/lib/intake/prepare.mjs

@@ -123,6 +123,8 @@ export async function prepareIntakeForIngestedFile({
   const tagSuggestions = suggestTags(triage, related, vocab);
 
   const baseEntry = {
+    // OWASP LLM01: externally-ingested document bodies are untrusted data, not instructions
+    trust: 'untrusted',
     intake: {
       sourcePath: ingestedFile.sourcePath,
       outputPath: ingestedFile.outputPath,