@geraldmaron/construct 1.0.11 → 1.0.14

package/lib/intake/poll-lock.mjs

@@ -0,0 +1,136 @@
+/**
+ * lib/intake/poll-lock.mjs — pid-stamped file lock around InboxWatcher.poll().
+ *
+ * Two pollers (the embed daemon and a manual `construct intake process`)
+ * share the same state file + manifest. Without serialization, both can
+ * decide a freshly-dropped file is unprocessed in the window between
+ * "read state" and "write state," producing two intake packets for one
+ * source. The lock makes one poll iteration atomic from the system's
+ * perspective: the second caller waits, retries until the timeout, or
+ * raises POLL_LOCK_BUSY for the CLI to render a clear refusal.
+ *
+ * Lockfile shape (JSON at <rootDir>/.cx/runtime/inbox-poll.lock):
+ *   { pid, actor, startedAt, timeoutAt? }
+ *
+ * Stale detection: a lock whose pid is gone, or whose timeoutAt has
+ * passed, is cleared on the next acquire attempt. Mirrors the
+ * lib/beads-lock.mjs API shape so callers familiar with one know the other.
+ */
+
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export const POLL_LOCK_REL_PATH = '.cx/runtime/inbox-poll.lock';
+export const POLL_LOCK_BUSY = 'POLL_LOCK_BUSY';
+
+function lockPathFor(rootDir) {
+  return join(rootDir, POLL_LOCK_REL_PATH);
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function afterMs(ms) {
+  return new Date(Date.now() + ms).toISOString();
+}
+
+function processExists(pid) {
+  if (!pid || typeof pid !== 'number') return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function readPollLock(rootDir) {
+  const p = lockPathFor(rootDir);
+  if (!existsSync(p)) return null;
+  try {
+    const raw = JSON.parse(readFileSync(p, 'utf8'));
+    if (!raw || typeof raw !== 'object') return null;
+    return raw;
+  } catch {
+    return null;
+  }
+}
+
+export function isPollLockStale(lock) {
+  if (!lock) return false;
+  if (lock.pid && !processExists(lock.pid)) return true;
+  if (lock.timeoutAt && new Date(lock.timeoutAt) < new Date()) return true;
+  return false;
+}
+
+function clearStale(rootDir) {
+  const lock = readPollLock(rootDir);
+  if (lock && isPollLockStale(lock)) {
+    rmSync(lockPathFor(rootDir), { force: true });
+    return true;
+  }
+  return false;
+}
+
+function writeLockFile(rootDir, lock) {
+  const p = lockPathFor(rootDir);
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, JSON.stringify(lock, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * Acquire the intake poll lock. Resolves with the lock object on success,
+ * rejects with an Error whose `code` is POLL_LOCK_BUSY when the wait window
+ * elapses without acquisition. The rejection's `holder` field carries the
+ * blocking lock's metadata for downstream error rendering.
+ */
+export async function acquirePollLock({
+  rootDir,
+  actor = 'unknown',
+  command = '',
+  waitMs = 0,
+  timeoutMs = 5 * 60 * 1000,
+  pollIntervalMs = 100,
+} = {}) {
+  if (!rootDir) throw new Error('acquirePollLock: rootDir is required');
+  const deadline = Date.now() + Math.max(0, waitMs);
+
+  while (true) {
+    clearStale(rootDir);
+    const existing = readPollLock(rootDir);
+    if (!existing) {
+      const lock = {
+        pid: process.pid,
+        actor,
+        command,
+        startedAt: nowIso(),
+        timeoutAt: timeoutMs > 0 ? afterMs(timeoutMs) : undefined,
+      };
+      writeLockFile(rootDir, lock);
+      return lock;
+    }
+    if (Date.now() >= deadline) {
+      const err = new Error(
+        `intake poll lock held by ${existing.actor || 'unknown'} (pid ${existing.pid}) since ${existing.startedAt}`,
+      );
+      err.code = POLL_LOCK_BUSY;
+      err.holder = existing;
+      throw err;
+    }
+    await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+  }
+}
+
+/**
+ * Release the lock iff the calling process owns it. Returns true on release,
+ * false when the lock was missing, expired, or owned by someone else.
+ */
+export function releasePollLock(rootDir) {
+  const lock = readPollLock(rootDir);
+  if (lock && lock.pid === process.pid) {
+    rmSync(lockPathFor(rootDir), { force: true });
+    return true;
+  }
+  return false;
+}

package/lib/intake/prepare.mjs

@@ -1,7 +1,7 @@
 /**
  * lib/intake/prepare.mjs — turn a fresh inbox ingestion into an R&D intake packet.
  *
- * Called by `InboxWatcher.poll()` after each successful file ingestion.
+ * Triggered by `InboxWatcher.poll()` after each successful file ingestion.
  * Four deterministic preparation steps, then write the result to the
  * intake queue:
  *
@@ -14,11 +14,16 @@
  *   4. Run classifyRdIntake to produce the R&D triage object (intake type,
  *      owner persona, recommended chain, action, risk).
  *
+ * After enqueue, fires a signal.promoted lifecycle event when the triage
+ * confidence crosses SIGNAL_PROMOTION_THRESHOLD (matches the default
+ * tag-vocabulary auto_threshold), so subscribers can act on confidently
+ * typed signals without polling the queue.
+ *
  * The agent — invoked manually or via session-start hook nudge — reads
  * the resulting `.cx/intake/pending/<id>.json` and does the real
  * comparison work (overlap with existing PRD? contradicts ADR? new RFC
- * candidate?). The daemon never calls an LLM. This separation keeps the
- * daemon cheap and predictable; the model spend stays with the agent.
+ * candidate?). The daemon never calls an LLM; the separation keeps the
+ * daemon cheap and predictable while model spend stays with the agent.
  */
 
 import { existsSync, readFileSync } from 'node:fs';
@@ -30,11 +35,19 @@ import { createIntakeQueue } from './queue.mjs';
 import { classifyRdIntake } from './classify.mjs';
 import { detectCustomerMentions, linkSignalToCustomer, updateCustomerProfile } from '../embed/customer-profiles.mjs';
 import { resolveActiveProfile } from '../profiles/loader.mjs';
+import { emitBestEffort as emitRoleEvent } from '../roles/event-bus.mjs';
+import { gatherAttribution, stampAttribution } from './attribution.mjs';
+import { MANIFEST_REL_PATH } from './manifest.mjs';
 
 const DEFAULT_RELATED_LIMIT = 5;
 const EXCERPT_CHARS = 800;
 const QUERY_CHARS = 500;
 
+// Confidence at which a triage signal is considered "promoted" from
+// uncertain to confidently classified. Mirrors the default tag-vocabulary
+// auto_threshold.
+const SIGNAL_PROMOTION_THRESHOLD = 0.70;
+
 export async function prepareIntakeForIngestedFile({
   rootDir,
   ingestedFile,
@@ -85,7 +98,7 @@ export async function prepareIntakeForIngestedFile({
 
   const droppedInfo = ingestedFile.droppedInfo ?? [];
 
-  const entry = {
+  const baseEntry = {
     intake: {
       sourcePath: ingestedFile.sourcePath,
       outputPath: ingestedFile.outputPath,
@@ -101,10 +114,35 @@ export async function prepareIntakeForIngestedFile({
     customers: customers.length ? customers : undefined,
   };
 
+  // Capability detection mirrors inbox.mjs: stamp provenance onto the packet
+  // when the project's intake manifest is present (init scaffolds it for
+  // archetype-enabled profiles). Keeps non-archetype packets shape-identical
+  // to the pre-attribution behavior so downstream consumers see no diff.
+
+  const archetypeOn = existsSync(`${rootDir}/${MANIFEST_REL_PATH}`);
+  const entry = archetypeOn ? stampAttribution(baseEntry, gatherAttribution({ cwd: rootDir })) : baseEntry;
+
   const intakeQueue = queue || createIntakeQueue(rootDir, env);
   const result = intakeQueue.enqueue(entry);
   const intakeId = result?.id || '';
 
+  // Promotion fires once a triage signal crosses the auto-classification
+  // threshold, giving subscribers a chance to act on a confidently typed
+  // signal without polling the intake queue.
+
+  if ((triage?.confidence ?? 0) >= SIGNAL_PROMOTION_THRESHOLD && triage?.intakeType && triage.intakeType !== 'unknown') {
+    emitRoleEvent('signal.promoted', {
+      summary: `${triage.intakeType} (${triage.confidence.toFixed(2)})`,
+      context: {
+        intakeId,
+        intakeType: triage.intakeType,
+        confidence: triage.confidence,
+        sourcePath: ingestedFile.sourcePath,
+        primaryOwner: triage.primaryOwner,
+      },
+    });
+  }
+
   // Update customer profiles with new evidence
   for (const mention of customerMentions) {
     try {

package/lib/logging/rotate.mjs

@@ -0,0 +1,394 @@
+/**
+ * lib/logging/rotate.mjs — shared file-rotation primitive.
+ *
+ * Two consumers need bounded log files: the trace writer
+ * (`.cx/traces/<date>.jsonl`, capped to avoid >100MB single-file commits
+ * that GitHub rejects) and the embed daemon stdout log
+ * (`~/.cx/runtime/embed-daemon.log`, capped so a stuck "Telemetry skipped"
+ * message can't fill the disk).
+ *
+ * `appendWithRotation` is for code paths that own the writes (the trace
+ * writer). `rotateIfOversized` is for externally-written files where Construct
+ * code only polls (the OS-supervisor stdout redirect — Construct never writes
+ * the embed log directly).
+ *
+ * Rotated segments are named `<base>.<n><ext>` where `n` starts at 1 and
+ * counts upward; with `gzip: true` segments get a `.gz` suffix and are
+ * compressed lazily on rotation. `maxSegments` (when set) drops the oldest
+ * `n>=maxSegments` segments on every rotation so the directory stays bounded.
+ */
+
+import { existsSync, statSync, renameSync, readdirSync, readFileSync, unlinkSync, appendFileSync, createReadStream, createWriteStream, mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { createGzip, gunzipSync } from 'node:zlib';
+import { pipeline } from 'node:stream/promises';
+
+/**
+ * Parse `<base>.<ext>` from a full path. `app.log` → base=app, ext=.log.
+ * `2026-05-28.jsonl` → base=2026-05-28, ext=.jsonl.
+ */
+function splitBase(filePath) {
+  const dir = path.dirname(filePath);
+  const ext = path.extname(filePath);
+  const base = path.basename(filePath, ext);
+  return { dir, base, ext };
+}
+
+/**
+ * Enumerate existing rotated segments for a given file, sorted ascending by
+ * segment index. Includes both compressed and uncompressed forms.
+ */
+function listSegments(filePath) {
+  const { dir, base, ext } = splitBase(filePath);
+  if (!existsSync(dir)) return [];
+
+  // Pattern: <base>.<n>[<ext>][.gz]. Match any segment that starts with base
+  // and a digit suffix; tolerate both `.1.jsonl` and `.1.jsonl.gz`.
+
+  const pattern = new RegExp(`^${escapeRegex(base)}\\.(\\d+)${escapeRegex(ext)}(\\.gz)?$`);
+  const entries = readdirSync(dir)
+    .map((name) => {
+      const m = name.match(pattern);
+      return m ? { name, index: Number(m[1]), gzipped: !!m[2] } : null;
+    })
+    .filter(Boolean)
+    .sort((a, b) => a.index - b.index);
+  return entries.map((e) => ({ ...e, fullPath: path.join(dir, e.name) }));
+}
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Rename current → next-segment, optionally gzipping the previous tail. Old
+ * segments past `maxSegments` are deleted. Returns the new segment path or
+ * null when no rotation happened.
+ */
+export async function rotateIfOversized(filePath, { maxBytes, maxSegments = 0, gzip = false } = {}) {
+  if (!maxBytes || maxBytes <= 0) return null;
+  if (!existsSync(filePath)) return null;
+
+  let stat;
+  try { stat = statSync(filePath); }
+  catch { return null; }
+  if (!stat.isFile() || stat.size < maxBytes) return null;
+
+  const { dir, base, ext } = splitBase(filePath);
+  const existing = listSegments(filePath);
+  const nextIndex = (existing[existing.length - 1]?.index ?? 0) + 1;
+
+  // Move current → <base>.<nextIndex><ext>. Then optionally gzip the rotated
+  // file. Doing the rename first means a concurrent writer that reopens the
+  // path lands on a fresh file with no data loss.
+
+  const rotatedPlain = path.join(dir, `${base}.${nextIndex}${ext}`);
+  renameSync(filePath, rotatedPlain);
+
+  let finalPath = rotatedPlain;
+  if (gzip) {
+    finalPath = `${rotatedPlain}.gz`;
+    try {
+      await pipeline(createReadStream(rotatedPlain), createGzip(), createWriteStream(finalPath));
+      try { unlinkSync(rotatedPlain); } catch { /* already cleaned up */ }
+    } catch {
+      // Compression failed; leave the plain rotated segment in place rather
+      // than losing data.
+
+      finalPath = rotatedPlain;
+    }
+  }
+
+  pruneSegments(filePath, maxSegments);
+  return finalPath;
+}
+
+/**
+ * Drop oldest segments past `maxSegments`. With maxSegments=0, keep every
+ * segment (no pruning). Always preserves the active file (which has no
+ * numeric suffix and is therefore not in the segment list).
+ */
+export function pruneSegments(filePath, maxSegments = 0) {
+  if (!maxSegments || maxSegments <= 0) return [];
+  const segments = listSegments(filePath);
+  if (segments.length <= maxSegments) return [];
+  const drop = segments.slice(0, segments.length - maxSegments);
+  for (const seg of drop) {
+    try { unlinkSync(seg.fullPath); } catch { /* already gone */ }
+  }
+  return drop.map((s) => s.fullPath);
+}
+
+/**
+ * Append `line` to `filePath`, rotating beforehand if the file would exceed
+ * `maxBytes`. Creates the parent directory on first append.
+ *
+ * Synchronous + best-effort gzip. The cost of compressing on rotation is
+ * amortized over `maxBytes` worth of writes, so the rotation tail rarely
+ * blocks the calling code path. When gzip:false rotation is just a rename.
+ */
+export async function appendWithRotation(filePath, line, { maxBytes, maxSegments = 0, gzip = false } = {}) {
+  const dir = path.dirname(filePath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+  if (maxBytes && maxBytes > 0 && existsSync(filePath)) {
+    try {
+      const stat = statSync(filePath);
+      // Rotate when this append would cross the cap, not after — keeps every
+      // single segment strictly under `maxBytes`.
+
+      if (stat.isFile() && stat.size + Buffer.byteLength(line) >= maxBytes) {
+        await rotateIfOversized(filePath, { maxBytes: 0, maxSegments, gzip });
+      }
+    } catch { /* fall through to plain append */ }
+  }
+
+  appendFileSync(filePath, line);
+}
+
+/**
+ * Sync variant for hot paths that can't `await` rotation. Skips gzip (which
+ * requires streams) but still renames + prunes. Use this in trace writers and
+ * other latency-sensitive append loops.
+ */
+export function appendWithRotationSync(filePath, line, { maxBytes, maxSegments = 0 } = {}) {
+  const dir = path.dirname(filePath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+  if (maxBytes && maxBytes > 0 && existsSync(filePath)) {
+    try {
+      const stat = statSync(filePath);
+      if (stat.isFile() && stat.size + Buffer.byteLength(line) >= maxBytes) {
+        const { dir: d, base, ext } = splitBase(filePath);
+        const existing = listSegments(filePath);
+        const nextIndex = (existing[existing.length - 1]?.index ?? 0) + 1;
+        renameSync(filePath, path.join(d, `${base}.${nextIndex}${ext}`));
+        pruneSegments(filePath, maxSegments);
+      }
+    } catch { /* fall through */ }
+  }
+
+  appendFileSync(filePath, line);
+}
+
+/**
+ * Per-channel resource limits. Every Construct logger has a documented
+ * cap here so disk usage is bounded by design, not by hope. New loggers
+ * MUST be registered; the `appendBounded` helper refuses to write to an
+ * unregistered channel.
+ *
+ * Sizes are conservative defaults chosen for a single-developer machine.
+ * Override via env var on a per-channel basis when the workload genuinely
+ * exceeds these (CI runners, multi-tenant team installs, long-lived
+ * background daemons).
+ */
+export const LIMITS = {
+  // Trace shards under .cx/traces/<date>.jsonl — capped below GitHub's
+  // 100 MB single-file ceiling. Bead construct-1vv5.
+
+  trace: {
+    maxBytes: 100 * 1024 * 1024,
+    maxSegments: 0,                    // keep all history; rotation is for the size cap, not retention
+    gzip: false,
+    envOverride: 'CONSTRUCT_TRACE_MAX_MB',
+  },
+
+  // OS-supervised stdout log at ~/.cx/runtime/embed-daemon.log. Bead
+  // construct-88i. Rotation is poll-style via the daemon scheduler.
+
+  'embed-daemon-log': {
+    maxBytes: 50 * 1024 * 1024,
+    maxSegments: 5,
+    gzip: true,
+    envOverride: 'CONSTRUCT_EMBED_LOG_MAX_MB',
+  },
+
+  // Per-edit audit of file reads. High traffic in active sessions.
+  // ~/.cx/audit-reads.jsonl.
+
+  'audit-reads': {
+    maxBytes: 25 * 1024 * 1024,
+    maxSegments: 4,
+    gzip: true,
+    envOverride: 'CONSTRUCT_AUDIT_READS_MAX_MB',
+  },
+
+  // Per-skill-call telemetry. ~/.cx/skill-calls.jsonl.
+
+  'skill-calls': {
+    maxBytes: 25 * 1024 * 1024,
+    maxSegments: 4,
+    gzip: true,
+    envOverride: 'CONSTRUCT_SKILL_CALLS_MAX_MB',
+  },
+
+  // Agent-dispatch log written by `lib/hooks/agent-tracker.mjs`. Path: ~/.cx/agent-log.jsonl.
+
+  'agent-log': {
+    maxBytes: 25 * 1024 * 1024,
+    maxSegments: 4,
+    gzip: true,
+    envOverride: 'CONSTRUCT_AGENT_LOG_MAX_MB',
+  },
+
+  // Pending role invocations across all projects. ~/.cx/role-pending.jsonl.
+
+  'role-pending': {
+    maxBytes: 10 * 1024 * 1024,
+    maxSegments: 2,
+    gzip: true,
+    envOverride: 'CONSTRUCT_ROLE_PENDING_MAX_MB',
+  },
+
+  // Intent verifications. ~/.cx/intent-verifications.jsonl.
+
+  'intent-verifications': {
+    maxBytes: 10 * 1024 * 1024,
+    maxSegments: 2,
+    gzip: true,
+    envOverride: 'CONSTRUCT_INTENT_VERIFICATIONS_MAX_MB',
+  },
+
+  // Contract postcondition violations. ~/.cx/contract-violations.jsonl.
+
+  'contract-violations': {
+    maxBytes: 10 * 1024 * 1024,
+    maxSegments: 2,
+    gzip: true,
+    envOverride: 'CONSTRUCT_CONTRACT_VIOLATIONS_MAX_MB',
+  },
+
+  // Bash-output warning flags appended by the bash-output-logger hook on
+  // every Bash tool use over the size threshold. ~/.cx/warn-flags.txt.
+
+  'bash-warn-flags': {
+    maxBytes: 5 * 1024 * 1024,
+    maxSegments: 2,
+    gzip: false,
+    envOverride: 'CONSTRUCT_BASH_WARN_FLAGS_MAX_MB',
+  },
+
+  // Per-turn cost ledger written by the Stop hook. Cross-project (so the
+  // user has one place to see spend across every project) — each entry
+  // carries a projectId tag so readers can split by project. Path:
+  // ~/.cx/session-cost.jsonl.
+
+  'session-cost': {
+    maxBytes: 25 * 1024 * 1024,
+    maxSegments: 4,
+    gzip: true,
+    envOverride: 'CONSTRUCT_SESSION_COST_MAX_MB',
+  },
+
+  // Tamper-evident audit trail of every mutation Construct (or a dispatched
+  // subagent) makes. Project-scoped. Path: <project>/.cx/audit-trail.jsonl.
+
+  'audit-trail': {
+    maxBytes: 50 * 1024 * 1024,
+    maxSegments: 4,
+    gzip: true,
+    envOverride: 'CONSTRUCT_AUDIT_TRAIL_MAX_MB',
+  },
+
+  // Pending typecheck queue written by the edit-accumulator hook on every
+  // Edit/Write of a TS/JS file. Path: ~/.cx/pending-typecheck.txt.
+
+  'edit-accumulator': {
+    maxBytes: 5 * 1024 * 1024,
+    maxSegments: 2,
+    gzip: false,
+    envOverride: 'CONSTRUCT_EDIT_ACCUMULATOR_MAX_MB',
+  },
+};
+
+/**
+ * Resolve the effective cap for a channel, honoring env-var overrides
+ * (interpreted as megabytes). Returns the byte budget; 0 disables rotation.
+ */
+function resolveCap(channel, env = process.env) {
+  const def = LIMITS[channel];
+  if (!def) throw new Error(`appendBounded: unknown channel "${channel}". Register it in lib/logging/rotate.mjs#LIMITS.`);
+  const raw = def.envOverride ? env[def.envOverride] : undefined;
+  if (raw === undefined) return def.maxBytes;
+  const mb = Number(raw);
+  if (!Number.isFinite(mb) || mb < 0) return def.maxBytes;
+  return Math.floor(mb * 1024 * 1024);
+}
+
+/**
+ * Append a line to `filePath` with rotation governed by the named channel's
+ * registered limit. Synchronous; renames the active file on overflow and
+ * prunes oldest segments past the channel's maxSegments. The registry
+ * guarantees nothing grows unbounded — every logger appending to a known
+ * channel inherits its documented disk budget.
+ */
+export function appendBounded(channel, filePath, line, env = process.env) {
+  const def = LIMITS[channel];
+  if (!def) throw new Error(`appendBounded: unknown channel "${channel}". Register it in lib/logging/rotate.mjs#LIMITS.`);
+  const maxBytes = resolveCap(channel, env);
+  return appendWithRotationSync(filePath, line, {
+    maxBytes,
+    maxSegments: def.maxSegments,
+  });
+}
+
+/**
+ * Last non-empty line written under the channel, looking across the active
+ * file and the rotated segments. Resolves the right value for chain-hash
+ * fields (`prev_line_hash`) on the first write after a rotation, where the
+ * active file is empty but the chain head lives at the tail of the most
+ * recent rotated segment (`<base>.<n><ext>` with the highest `n`, possibly
+ * `.gz`-suffixed).
+ *
+ * Sync. Reads the WHOLE most-recent gzipped segment in memory when it has
+ * to fall back to one; segment caps in LIMITS keep the worst case bounded
+ * (audit-trail tops out at 50 MB raw, ~5–10 MB gzipped).
+ *
+ * Returns the line WITHOUT its trailing newline, or null when no data has
+ * ever been written for the channel.
+ */
+export function readLastLineAcrossSegments(filePath) {
+  if (existsSync(filePath)) {
+    const lastFromActive = readLastLineOfFile(filePath);
+    if (lastFromActive !== null) return lastFromActive;
+  }
+  const segments = listSegments(filePath);
+  if (segments.length === 0) return null;
+  const newest = segments[segments.length - 1];
+  try {
+    const raw = readFileSync(newest.fullPath);
+    const decoded = newest.gzipped ? gunzipSync(raw) : raw;
+    return lastLineOfBuffer(decoded);
+  } catch {
+    return null;
+  }
+}
+
+function lastLineOfBuffer(buf) {
+  let end = buf.length;
+  while (end > 0 && buf[end - 1] === 0x0a) end -= 1;
+  if (end === 0) return null;
+  let start = end - 1;
+  while (start > 0 && buf[start - 1] !== 0x0a) start -= 1;
+  return buf.slice(start, end).toString('utf8');
+}
+
+function readLastLineOfFile(filePath) {
+  try {
+    if (statSync(filePath).size === 0) return null;
+
+    // Read the whole file and walk back to the last newline boundary. A
+    // bounded tail read (e.g. last 8 KB) would truncate JSONL records that
+    // exceed the window — the audit-trail's `content_hash` field can put a
+    // record over 50 KB — and a truncated string would break the
+    // prev_line_hash chain it feeds. Per-channel size caps in LIMITS bound
+    // the worst-case allocation here.
+
+    return lastLineOfBuffer(readFileSync(filePath));
+  } catch {
+    return null;
+  }
+}
+
+/** Re-export for convenient testing. */
+export const __test = { listSegments, splitBase, resolveCap, readLastLineOfFile };

package/lib/mcp/tools/project.mjs

@@ -281,7 +281,7 @@ export function projectContext(args, { ROOT_DIR }) {
   const has_context_file = contextInspection.hasFile;
   const workflow = loadWorkflow(cwd);
   const mergedEnv = loadConstructEnv({ rootDir: ROOT_DIR, homeDir: homedir(), env: process.env });
-  const registry = readJSON(join(ROOT_DIR, 'agents', 'registry.json')) ?? {};
+  const registry = readJSON(join(ROOT_DIR, 'specialists', 'registry.json')) ?? {};
   const executionContractModel = resolveExecutionContractModelMetadata({
     envValues: mergedEnv,
     registryModels: registry.models ?? {},
@@ -323,7 +323,7 @@ export function workflowStatus(args, { ROOT_DIR }) {
   const workflow = loadWorkflow(cwd);
   const workflowHealth = inspectWorkflowHealth(workflow, { cwd });
   const mergedEnv = loadConstructEnv({ rootDir: ROOT_DIR, homeDir: homedir(), env: process.env });
-  const registry = readJSON(join(ROOT_DIR, 'agents', 'registry.json')) ?? {};
+  const registry = readJSON(join(ROOT_DIR, 'specialists', 'registry.json')) ?? {};
   const executionContractModel = resolveExecutionContractModelMetadata({
     envValues: mergedEnv,
     registryModels: registry.models ?? {},

package/lib/mcp/tools/telemetry.mjs

@@ -70,7 +70,7 @@ function resolveSessionContext() {
 
 export async function cxTrace(args, { ROOT_DIR }) {
   const ctx = resolveSessionContext();
-  const registry = readJSON(join(ROOT_DIR, 'agents', 'registry.json')) ?? {};
+  const registry = readJSON(join(ROOT_DIR, 'specialists', 'registry.json')) ?? {};
   const registryModels = registry.models ?? {};
   const currentModels = readCurrentModels(join(ROOT_DIR, '.env'), registryModels, process.env);
   const route = typeof args.input === 'string' ? routeRequest({ request: args.input }) : null;

package/lib/opencode-config.mjs

@@ -47,8 +47,15 @@ export function sanitizeOpenCodeConfig(config) {
 }
 
 export function writeOpenCodeConfig(config, file = findOpenCodeConfigPath()) {
+  // Treat the canonical home config as the default target; any explicit path
+  // outside the canonical home dir (e.g. project-scoped .opencode/config.json)
+  // is honored as-is so per-project sync writes to the right tree.
+
   const canonical = getCanonicalOpenCodeConfigPath();
-  fs.mkdirSync(path.dirname(canonical), { recursive: true });
-  fs.writeFileSync(canonical, `${JSON.stringify(sanitizeOpenCodeConfig(config), null, 2)}\n`, "utf8");
-  return canonical;
+  const target = file && path.resolve(file) !== path.resolve(findOpenCodeConfigPath())
+    ? file
+    : canonical;
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, `${JSON.stringify(sanitizeOpenCodeConfig(config), null, 2)}\n`, "utf8");
+  return target;
 }