@geraldmaron/construct 1.0.12 → 1.0.15

package/lib/embed/docs-lifecycle.mjs

@@ -3,6 +3,8 @@
  *
  * Responsibilities:
  *   - Detect stale, missing, or outdated docs across targets
+ *   - Emit document.stale lifecycle events for each stale gap surfaced
+ *     (consumed by cx-docs-keeper and any project-bound subscribers)
  *   - Generate/update docs as artifacts in the appropriate docs lane
  *   - Route writes through the authority guard (direct-write for low-risk, approval-queued for high-risk)
  *   - Treat ALL doc types uniformly: adrs, prds, memos, notes, intake, roadmaps
@@ -23,6 +25,7 @@ import { WORKSPACE_DOCS_LANES } from './config.mjs';
 import { recommendArtifacts } from './artifact.mjs';
 import { createRecommendation, autoSuppressStale, recommendationStats, isRecommendationActive } from './recommendation-store.mjs';
 import { detectConflicts } from './conflict-detection.mjs';
+import { emitBestEffort as emitRoleEvent } from '../roles/event-bus.mjs';
 
 /**
  * Risk classification for doc operations.
@@ -232,6 +235,22 @@ export async function runDocsLifecycle(opts) {
     const gaps = detectDocGaps(target, { snapshot, roleLens });
     allGaps.push(...gaps.map((g) => ({ ...g, target: targetLabel(target) })));
 
+    // Surface staleness as lifecycle events for any specialist subscribed
+    // to document.stale (cx-docs-keeper by default).
+
+    for (const gap of gaps) {
+      if (gap.type !== 'stale') continue;
+      emitRoleEvent('document.stale', {
+        summary: gap.summary,
+        context: {
+          lane: gap.lane,
+          file: gap.file,
+          ageMs: gap.age,
+          target: targetLabel(target),
+        },
+      });
+    }
+
     // Check intake patterns for artifact recommendations (uses recommendation store for dedup)
     const intakeGaps = detectIntakeDocGaps(target.path);
     for (const gap of intakeGaps) {

package/lib/embed/inbox.mjs

@@ -33,10 +33,14 @@ import { shouldCreateCx } from '../project-detection.mjs';
 import { ensureCxDir } from '../project-init-shared.mjs';
 import { prepareIntakeForIngestedFile } from '../intake/prepare.mjs';
 import { loadIntakeConfig, INTAKE_DEFAULT_MAX_DEPTH } from '../intake/intake-config.mjs';
+import { loadManifest, recordFile, hasFile, sha256Of, MANIFEST_REL_PATH } from '../intake/manifest.mjs';
+import { gatherAttribution } from '../intake/attribution.mjs';
+import { acquirePollLock, releasePollLock } from '../intake/poll-lock.mjs';
 
 const STATE_FILE = '.cx/runtime/inbox-state.json';
 const DEFAULT_INBOX_SUBDIR = '.cx/inbox';
 const DOCS_INTAKE_SUBDIR = 'docs/intake';
+const ARCHETYPE_INBOX_SUBDIR = 'inbox';
 const MAX_FILE_SIZE_BYTES = 50 * 1024 * 1024; // 50 MB hard cap
 const STALE_STATE_AGE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
 
@@ -155,6 +159,16 @@ export function resolveInboxDirs(rootDir, env = process.env) {
     if (existsSync(docsIntake)) dirs.push(docsIntake);
   }
 
+  // Archetype inbox is a profile-driven drop zone for raw source files
+  // (capabilities.intake.inbox). Off by default; init flips it on when the
+  // active profile declares the capability so non-archetype projects keep
+  // their pre-Piece-C behavior.
+
+  if (config.includeArchetypeInbox) {
+    const archetypeInbox = join(rootDir, ARCHETYPE_INBOX_SUBDIR);
+    if (existsSync(archetypeInbox)) dirs.push(archetypeInbox);
+  }
+
   for (const candidate of config.parentDirs) {
     if (!candidate) continue;
     if (!existsSync(candidate)) continue;
@@ -298,8 +312,31 @@ export class InboxWatcher {
   /**
    * Scan all inbox dirs, ingest new files, record observations.
    * Returns { processed: [...], skipped: number, errors: [...] }
+   *
+   * @param {object} [opts]
+   * @param {number} [opts.waitMs] - When >0, block up to this many ms for
+   *   the intake poll lock. Default 0 (fail-fast). The CLI sets this when
+   *   the operator opts into waiting; the daemon's tick keeps the default
+   *   so a stuck poll does not stall the next scheduled iteration.
+   * @param {string} [opts.actor] - Stamped onto the lock for diagnostics.
    */
-  async poll() {
+  async poll({ waitMs = 0, actor = 'inbox-watcher' } = {}) {
+    let lockHeld = false;
+    try {
+      await acquirePollLock({
+        rootDir: this.#rootDir,
+        actor,
+        command: 'InboxWatcher.poll',
+        waitMs,
+      });
+      lockHeld = true;
+      return await this.#pollLocked();
+    } finally {
+      if (lockHeld) releasePollLock(this.#rootDir);
+    }
+  }
+
+  async #pollLocked() {
     const config = loadIntakeConfig(this.#rootDir, this.#env);
     const dirs = resolveInboxDirs(this.#rootDir, this.#env);
     const state = readState(this.#rootDir);
@@ -307,6 +344,15 @@ export class InboxWatcher {
     const errors = [];
     let skipped = 0;
 
+    // Capability detection: SHA-256 dedup is enabled when the project's
+    // intake manifest exists (init scaffolds it for the archetype). Hashing
+    // is only paid when the manifest is in use, so non-archetype projects
+    // keep the original fast path.
+
+    const manifestPath = join(this.#rootDir, MANIFEST_REL_PATH);
+    const manifestEnabled = existsSync(manifestPath);
+    const attribution = manifestEnabled ? gatherAttribution({ cwd: this.#rootDir }) : null;
+
     for (const dir of dirs) {
       const candidates = scanDir(dir, config.maxDepth);
       for (const candidate of candidates) {
@@ -319,6 +365,27 @@ export class InboxWatcher {
           continue;
         }
 
+        // Manifest dedup: a file with identical content under any path is
+        // a duplicate. Catches renames, copies, and re-drops the state
+        // check misses. Skipped here without consuming the ingest budget.
+
+        let candidateSha = null;
+        if (manifestEnabled) {
+          try {
+            const bytes = readFileSync(candidate.path);
+            candidateSha = sha256Of(bytes);
+            if (hasFile(this.#rootDir, candidateSha)) {
+              skipped += 1;
+              state[key] = { mtimeMs: candidate.mtimeMs, processedAt: new Date().toISOString(), dedupHash: candidateSha };
+              continue;
+            }
+          } catch (err) {
+            if (this.#env.CONSTRUCT_DEBUG_INTAKE === '1') {
+              process.stderr.write(`[inbox] sha256 hashing failed for ${candidate.path}: ${err.message}\n`);
+            }
+          }
+        }
+
         try {
           const { category, knowledgeSubdir } = inferFileClassification(candidate.path);
           const result = await ingestDocuments([candidate.path], {
@@ -381,7 +448,23 @@ export class InboxWatcher {
             }
 
             state[key] = { mtimeMs: candidate.mtimeMs, processedAt: new Date().toISOString(), outputPath: fileResult.outputPath };
-            processed.push({ path: candidate.path, outputPath: fileResult.outputPath, docsPath, characters: fileResult.characters, knowledgeSubdir, intakeId });
+
+            if (manifestEnabled && candidateSha) {
+              try {
+                recordFile(this.#rootDir, candidateSha, {
+                  sourcePath: candidate.path,
+                  intakeId,
+                  createdBy: attribution?.createdBy ?? null,
+                  createdByAgent: attribution?.createdByAgent ?? null,
+                });
+              } catch (err) {
+                if (this.#env.CONSTRUCT_DEBUG_INTAKE === '1') {
+                  process.stderr.write(`[inbox] manifest record failed for ${candidate.path}: ${err.message}\n`);
+                }
+              }
+            }
+
+            processed.push({ path: candidate.path, outputPath: fileResult.outputPath, docsPath, characters: fileResult.characters, knowledgeSubdir, intakeId, dedupHash: candidateSha });
           }
         } catch (err) {
           // Audio/video files cannot be text-extracted without ASR. Route to

package/lib/embed/recommendation-store.mjs

@@ -18,11 +18,20 @@
  * Prioritization formula:
  *   score = (signalCount * 2) + (customerImpact * 3) + (recencyBonus) + (strategicBonus)
  *   P0: score >= 10, P1: >= 7, P2: >= 4, P3: < 4
+ *
+ * Enrichment state machine: every new record starts with state: 'raw'. The
+ * enrichment loop (subscriber to recommendation.generated, lifecycle event
+ * emitted from createRecommendation on the new-record path only) transitions
+ * raw → enriching → enriched | enrichment_failed and writes enrichedAt /
+ * enrichedBy / framingNotes back to the index. Dedup-update path does not
+ * re-emit so a steady drip of signals against the same recommendation does
+ * not retrigger enrichment.
  */
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync, appendFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { randomUUID } from 'node:crypto';
+import { emitBestEffort } from '../roles/event-bus.mjs';
 import { cxDir } from '../paths.mjs';
 import { hasSqlStore } from '../storage/sql-store.mjs';
 import { createSqlClient } from '../storage/backend.mjs';
@@ -161,6 +170,9 @@ export function createRecommendation({ type, title, reason, signalCount = 1, cus
     supersededAt: null,
     supersededById: null,
     suppressedUntil: null,
+    state: 'raw',
+    enrichedAt: null,
+    enrichedBy: null,
   };
 
   // Append to log
@@ -171,6 +183,23 @@ export function createRecommendation({ type, title, reason, signalCount = 1, cus
   writeIndex(index);
 
   createRecommendationPgBestEffort(rec, project, env);
+
+  // Surfaces the new recommendation as a lifecycle event so the enrichment
+  // loop (and any project-bound subscribers in .cx/specialists/) can route
+  // the matched specialist's contract chain against it.
+
+  emitBestEffort('recommendation.generated', {
+    project: project || '',
+    summary: `${rec.type}: ${rec.title}`,
+    context: {
+      recommendationId: rec.id,
+      dedupKey: key,
+      priority: rec.priority,
+      score: rec.score,
+      artifactType: rec.type,
+    },
+  });
+
   return { id, dedupKey: key, priority: rec.priority, score, existing: false };
 }
 

package/lib/flavors/loader.mjs

@@ -6,7 +6,7 @@
  *   - validateFlavor(path) — frontmatter conformance check against the schema
  *   - perRoleFlavorCount(profile) — flavor counts per role for cap enforcement
  *
- * The cap is enforced at sync time and in lint-prose's sibling lint-flavors.
+ * The cap is enforced at sync time and in lint-profiles.
  * Six flavors per role per profile is the current ceiling; bumping requires
  * an ADR. Existing roles like qa already have 6, so the cap is set tight.
  */

package/lib/gates-audit.mjs

@@ -41,18 +41,24 @@ const DEFAULT_ROOT_DIR = join(MODULE_DIR, '..');
 const MERGE_AGGREGATOR = 'ci-required';
 
 const GATE_DEFINITIONS = [
-  { ciJob: 'test (ubuntu-latest / node 22)', prePushLabel: 'tests', critical: true, requireMergeVia: MERGE_AGGREGATOR },
-  { ciJob: 'test (macos-latest / node 22)',  prePushLabel: 'tests', critical: true, requireMergeVia: MERGE_AGGREGATOR },
-  { ciJob: 'test (ubuntu-latest / node 20)', prePushLabel: 'tests', critical: true, requireMergeVia: MERGE_AGGREGATOR },
-  { ciJob: 'test (macos-latest / node 20)',  prePushLabel: 'tests', critical: true, requireMergeVia: MERGE_AGGREGATOR },
-  { ciJob: 'retrieval evals',                prePushLabel: 'evals', critical: true, requireMergeVia: MERGE_AGGREGATOR },
-  { ciJob: 'dependency CVE audit',           prePushLabel: 'audit', critical: true, requireMergeVia: MERGE_AGGREGATOR },
-  { ciJob: 'secret scanning',                prePushLabel: null,  preCommitCheck: 'ECC secret scan',               critical: true, note: 'pre-commit ECC scan covers a subset of gitleaks rules' },
-  { ciJob: 'postgres + pgvector integration', prePushLabel: null, preCommitCheck: null,                            critical: false, note: 'CI-only: requires Docker Postgres + pgvector container; not practical locally', localMirror: 'ci-only', requireMergeVia: MERGE_AGGREGATOR },
-  { ciJob: 'docs drift check',               prePushLabel: 'docs', critical: true, requireMergeVia: MERGE_AGGREGATOR },
-  { ciJob: 'comment policy',                 prePushLabel: null,  preCommitCheck: 'Construct comment-lint', critical: true, note: 'pre-commit Construct policy section calls `lint:comments` across the full worktree', requireMergeVia: MERGE_AGGREGATOR },
-  { ciJob: 'template policy',                prePushLabel: null,  preCommitGhPrIntercept: true,                    critical: true, note: 'pre-push-gate intercepts `gh pr create` / `gh pr edit` and lints the body', requireMergeVia: MERGE_AGGREGATOR },
-  { ciJob: MERGE_AGGREGATOR,                 prePushLabel: null,  preCommitCheck: null,                            critical: true, note: 'aggregator: succeeds iff every wrapped conditional job in ci.yml ended in success or skipped', localMirror: 'ci-only' },
+  // Test, build, audit, evals, docs-drift, comment-policy, prose, profiles —
+  // all CI-only. The local pre-push gate was shrunk to claude/* refusal +
+  // SHA-aware red-CI re-push check + PR body lint; CI is the source of
+  // truth for everything else (see CHANGELOG entry "Pre-push hooks shrunk
+  // to local-only signals; CI is the source of truth" and the inverted
+  // contract enforced by tests/ci-parity.test.mjs).
+  { ciJob: 'test (ubuntu-latest / node 22)', prePushLabel: null, critical: true, requireMergeVia: MERGE_AGGREGATOR, localMirror: 'ci-only' },
+  { ciJob: 'test (macos-latest / node 22)',  prePushLabel: null, critical: true, requireMergeVia: MERGE_AGGREGATOR, localMirror: 'ci-only' },
+  { ciJob: 'test (ubuntu-latest / node 20)', prePushLabel: null, critical: true, requireMergeVia: MERGE_AGGREGATOR, localMirror: 'ci-only' },
+  { ciJob: 'test (macos-latest / node 20)',  prePushLabel: null, critical: true, requireMergeVia: MERGE_AGGREGATOR, localMirror: 'ci-only' },
+  { ciJob: 'retrieval evals',                prePushLabel: null, critical: true, requireMergeVia: MERGE_AGGREGATOR, localMirror: 'ci-only' },
+  { ciJob: 'dependency CVE audit',           prePushLabel: null, critical: true, requireMergeVia: MERGE_AGGREGATOR, localMirror: 'ci-only' },
+  { ciJob: 'secret scanning',                prePushLabel: null, preCommitCheck: 'ECC secret scan', critical: true, note: 'pre-commit ECC scan covers a subset of gitleaks rules' },
+  { ciJob: 'postgres + pgvector integration', prePushLabel: null, preCommitCheck: null, critical: false, note: 'CI-only: requires Docker Postgres + pgvector container; not practical locally', localMirror: 'ci-only', requireMergeVia: MERGE_AGGREGATOR },
+  { ciJob: 'docs drift check',               prePushLabel: null, critical: true, requireMergeVia: MERGE_AGGREGATOR, localMirror: 'ci-only' },
+  { ciJob: 'comment policy',                 prePushLabel: null, preCommitCheck: 'Construct comment-lint', critical: true, note: 'pre-commit Construct policy section calls `lint:comments` across the full worktree', requireMergeVia: MERGE_AGGREGATOR },
+  { ciJob: 'template policy',                prePushLabel: null, preCommitGhPrIntercept: true, critical: true, note: 'pre-push-gate intercepts `gh pr create` / `gh pr edit` and lints the body', requireMergeVia: MERGE_AGGREGATOR },
+  { ciJob: MERGE_AGGREGATOR,                 prePushLabel: null, preCommitCheck: null, critical: true, note: 'aggregator: succeeds iff every wrapped conditional job in ci.yml ended in success or skipped', localMirror: 'ci-only' },
 ];
 
 function parseCIJobs(rootDir) {

package/lib/handoffs/contract.mjs

@@ -38,7 +38,7 @@
  *
  * `parseHandoff` is intentionally permissive — pre-contract handoffs with
  * no frontmatter still parse with status='legacy' so they aren't lost.
- * `validateHandoff` is the strict version, used when writing.
+ * `validateHandoffFile` is the strict version, used when writing.
  */
 
 import { readFileSync } from 'node:fs';
@@ -109,7 +109,7 @@ export function parseHandoffFile(filePath) {
   return parseHandoff(text);
 }
 
-export function validateHandoff(parsed) {
+export function validateHandoffFile(parsed) {
   const errors = [];
   const fm = parsed?.frontmatter || {};
   if (fm.schema !== HANDOFF_SCHEMA_VERSION) errors.push(`schema must be '${HANDOFF_SCHEMA_VERSION}'`);

package/lib/hooks/_lib/input.mjs

@@ -0,0 +1,52 @@
+/**
+ * lib/hooks/_lib/input.mjs — shared hook input parsing.
+ *
+ * Claude Code passes hook input as JSON on stdin. Codex and OpenCode (when
+ * they ship hook support) pass via TOOL_INPUT_FILE_PATH env or argv. This
+ * helper normalizes all three so a hook reads one shape regardless of the
+ * host transport. Hooks should call `readHookInput()` once at startup and
+ * branch on `input.tool_name` from there.
+ *
+ * Returns an object with at minimum `tool_name` and `tool_input` fields,
+ * plus any fields present in the source payload. Empty object on parse
+ * failure (the hook is then free to exit 0 silently if no useful input
+ * landed — matches the existing convention).
+ */
+
+import { readFileSync } from 'node:fs';
+
+export function readHookInput({ env = process.env, argv = process.argv } = {}) {
+  const stdin = tryReadStdin();
+  if (stdin) {
+    const parsed = tryParseJson(stdin);
+    if (parsed && typeof parsed === 'object') return parsed;
+  }
+
+  const envPath = env.TOOL_INPUT_FILE_PATH;
+  if (envPath) {
+    try {
+      const raw = readFileSync(envPath, 'utf8');
+      const parsed = tryParseJson(raw);
+      if (parsed && typeof parsed === 'object') return parsed;
+      return { tool_input: { file_path: envPath } };
+    } catch { /* fall through */ }
+  }
+
+  const argvJsonPos = argv.findIndex((a) => a === '--input-json');
+  if (argvJsonPos >= 0 && argv[argvJsonPos + 1]) {
+    const parsed = tryParseJson(argv[argvJsonPos + 1]);
+    if (parsed && typeof parsed === 'object') return parsed;
+  }
+
+  return {};
+}
+
+function tryReadStdin() {
+  try { return readFileSync(0, 'utf8'); }
+  catch { return null; }
+}
+
+function tryParseJson(s) {
+  try { return JSON.parse(s); }
+  catch { return null; }
+}

package/lib/hooks/adaptive-lint.mjs

@@ -8,6 +8,10 @@
  *
  * @p95ms 800
  * @maxBlockingScope none (PostToolUse, non-blocking)
+ *
+ * @lifecycle PostToolUse
+ * @matcher  Write|Edit
+ * @exits 0 = pass
  */
 import { execSync } from 'child_process';
 import { existsSync, readFileSync } from 'fs';

package/lib/hooks/agent-tracker.mjs

@@ -1,16 +1,34 @@
 #!/usr/bin/env node
 /**
- * lib/hooks/agent-tracker.mjs — Agent task lifecycle hook — tracks task start, completion, and handoffs.
+ * lib/hooks/agent-tracker.mjs — Task tool lifecycle hook: records dispatch +
+ * outcome and enqueues `next:cx-<role>` handoffs.
  *
- * Runs as PostToolUse after Agent tool calls. Records agent invocations and their outcomes to ~/.cx/agent-log.json for telemetry and performance review.
- * Also records observations for learning system to identify patterns/anti-patterns.
+ * Runs as PostToolUse after Task. Writes the agent-log to the project-scoped
+ * .cx/agent-log.jsonl, captures success/failure observations under
+ * .cx/observations/, and enqueues handoffs into ~/.cx/role-pending.jsonl
+ * (kept user-scope because a handoff may legitimately span projects; each
+ * entry carries a projectId tag for attribution).
+ *
+ * Handoffs also emit a `handoff.received` lifecycle event via the role
+ * event-bus for observability. The direct role-pending write stays the
+ * source of truth until the gateway becomes an event-bus consumer; the
+ * emit is the bridge that makes the dispatch observable through the same
+ * surface as every other lifecycle event.
  *
  * @p95ms 10
  * @maxBlockingScope none (PostToolUse, non-blocking)
+ *
+ * @lifecycle PostToolUse
+ * @matcher  Task
+ * @exits 0 = pass
  */
-import { readFileSync, writeFileSync, mkdirSync, existsSync, appendFileSync } from 'fs';
-import { join } from 'path';
-import { homedir } from 'os';
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { appendBounded } from '../logging/rotate.mjs';
+import { resolveProjectScopedPath } from '../project-root.mjs';
+import { emit as emitRoleEvent } from '../roles/event-bus.mjs';
+import { logHookFailure } from './_lib/log.mjs';
 
 let input = {};
 try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
@@ -67,8 +85,11 @@ try {
   const safeName = agentName.replace(/[^a-z0-9._-]/gi, '_');
   writeFileSync(join(cxDir, `last-agent-${safeName}.json`), JSON.stringify(agentEntry));
   
-  // Append to agent log for telemetry
-  const agentLogFile = join(cxDir, 'agent-log.jsonl');
+  // Per-project agent log (was ~/.cx/agent-log.jsonl which mixed every
+  // project's dispatches into one stream). Falls back to ~/.cx/ when the
+  // hook fires outside a Construct project.
+
+  const agentLogFile = resolveProjectScopedPath('agent-log.jsonl', { ensureDir: false });
   const logEntry = {
     timestamp: new Date().toISOString(),
     agent: agentName,
@@ -79,7 +100,7 @@ try {
     toolInputKeys: Object.keys(toolInput).filter(k => !k.includes('secret') && !k.includes('password') && !k.includes('token'))
   };
   
-  appendFileSync(agentLogFile, JSON.stringify(logEntry) + '\n');
+  appendBounded('agent-log', agentLogFile, JSON.stringify(logEntry) + '\n');
   
   // Record observation for pattern learning (only if we have meaningful outcome)
   if (outcome !== 'unknown' && description.length > 10) {
@@ -150,9 +171,8 @@ try {
     }
   }
   
-} catch (error) {
-  // Non-critical - best effort tracking
-  console.error(`Agent tracker error: ${error.message}`);
+} catch (err) {
+  logHookFailure({ hook: 'agent-tracker', err, phase: 'main' });
 }
 
 // Auto-enqueue handoff when a completing persona's result references
@@ -165,12 +185,18 @@ try {
     const unique = [...new Set(matches)];
     if (unique.length > 0) {
       const { isOnboarded, loadManifest } = await import('../roles/manifest.mjs');
+      // role-pending stays at user scope (a handoff might span projects),
+      // but each entry gets a projectId tag so a reader can attribute it.
+
       const pendingPath = join(homedir(), '.cx', 'role-pending.jsonl');
+      const { resolveProjectScope } = await import('../project-root.mjs');
+      const scope = resolveProjectScope();
       const bdMatch = /\b(construct-[a-z0-9]+)\b/i.exec(resultText) || [];
       const bdIssueId = bdMatch[1] || null;
       for (const targetId of unique) {
         if (!isOnboarded(targetId)) continue;
         const manifest = loadManifest(targetId);
+        const summary = `Handoff from ${agentName}${bdIssueId ? ` (re ${bdIssueId})` : ''}`;
         const entry = {
           ts: Date.now(),
           personaId: targetId,
@@ -178,15 +204,33 @@ try {
           bdIssueId,
           fingerprint: `handoff-${agentName}-${targetId}-${Date.now().toString(36)}`,
           eventType: 'handoff.received',
-          summary: `Handoff from ${agentName}${bdIssueId ? ` (re ${bdIssueId})` : ''}`,
+          summary,
           killSwitchEnv: manifest?.killSwitchEnv || '',
           handoffFrom: agentName,
+          ...(scope?.projectId ? { projectId: scope.projectId } : {}),
         };
-        appendFileSync(pendingPath, JSON.stringify(entry) + '\n');
+        appendBounded('role-pending', pendingPath, JSON.stringify(entry) + '\n');
+
+        // Mirror the handoff to the event bus so the dispatch is observable
+        // alongside every other lifecycle event. Best-effort: a bus failure
+        // does not affect the role-pending source of truth above.
+        try {
+          emitRoleEvent('handoff.received', {
+            project: scope?.projectId || '',
+            summary,
+            context: {
+              targetCxId: `cx-${targetId}`,
+              handoffFrom: agentName,
+              bdIssueId,
+            },
+          });
+        } catch { /* swallow */ }
       }
     }
   }
-} catch { /* best effort — handoff enqueue never blocks */ }
+} catch (err) {
+  logHookFailure({ hook: 'agent-tracker', err, phase: 'handoff' });
+}
 
 // Helper functions for learning system
 function extractKeywords(text) {