@khoavu882/doflow 2.0.0-beta.4 → 2.0.0

package/src/runtime/knowledge/semble-provider.js

@@ -0,0 +1,365 @@
+'use strict';
+
+// Optional pinned external provider. No imports, model loads or writes occur until invoked.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const zlib = require('node:zlib');
+const { spawn, spawnSync } = require('node:child_process');
+const { defaultIsAlive } = require('../../state/run-lock.js');
+const SEMBLE_VERSION = '0.7.0';
+const SEMBLE_LIMITS = Object.freeze({ files: 2000, fileBytes: 1048576, sourceBytes: 67108864,
+  chunks: 50000, artifactBytes: 268435456, modelBytes: 536870912, outputBytes: 2097152,
+  statsBytes: 65536, libraryBytes: 134217728, queryMs: 10000, lifecycleMs: 120000, changedFiles: 500, changedBytes: 16777216 });
+const digest = (value     )         => crypto.createHash('sha256').update(value).digest('hex');
+function fault(reason        , freshness = 'UNKNOWN', cause         )      { return Object.assign(new Error(reason), { reason, freshness, ...(cause ? { cause } : {}) }); }
+// Semble's own interpreter, found without a PATH wrapper: the `semble` launcher (PATH, then ~/.local/bin/semble) and the
+// absolute interpreter its shebang names. The bridge then proves offline that this interpreter imports the pinned version.
+// Ceiling: only a plain absolute shebang (uv/pipx layout); `env` indirection, arguments or a native launcher are unavailable.
+function resolveSembleInterpreter({ env = process.env, home = os.homedir() }      = {})      {
+  const dirs = String(env.PATH || '').split(path.delimiter).filter((dir        ) => path.isAbsolute(dir));
+  const launcher = [...dirs.map((dir        ) => path.join(dir, 'semble')), path.join(home, '.local', 'bin', 'semble')]
+    .find((file        ) => { try { return fs.statSync(file).isFile(); } catch { return false; } });
+  if (!launcher) throw fault('provider-unavailable', 'UNKNOWN', 'no semble launcher on PATH or in ~/.local/bin');
+  const head = Buffer.alloc(1024); const fd = fs.openSync(launcher, 'r');
+  let count = 0; try { count = fs.readSync(fd, head, 0, head.length, 0); } finally { fs.closeSync(fd); }
+  const shebang = /^#!(\/\S+)[ \t]*\r?$/.exec(head.subarray(0, count).toString('utf8').split('\n')[0]);
+  if (!shebang || path.basename(shebang[1]) === 'env') throw fault('provider-unavailable', 'UNKNOWN', `${launcher} does not name an absolute interpreter`);
+  let usable = false; try { fs.accessSync(shebang[1], fs.constants.X_OK); usable = fs.statSync(shebang[1]).isFile(); } catch {}
+  if (!usable) throw fault('provider-unavailable', 'UNKNOWN', `interpreter ${shebang[1]} named by ${launcher} is not executable`);
+  return { python: shebang[1], launcher };
+}
+// Lifecycle preflight: the interpreter's installed Semble metadata must be the pin before any lock or mutation. No
+// import, network or write happens here; the bridge re-checks the same pin under its audit policy on every call.
+function checkSembleVersion(python        )       {
+  const run = spawnSync(python, ['-c', 'import importlib.metadata as m, sys; sys.stdout.write(m.version("semble"))'], { cwd: path.dirname(python),
+    env: { ...process.env, PYTHONDONTWRITEBYTECODE: '1' }, encoding: 'utf8', timeout: 5000, maxBuffer: 4096 });
+  if (run.error || run.status !== 0) throw fault('provider-unavailable', 'UNKNOWN', `semble is not installed for ${python}`);
+  const found = String(run.stdout).trim().slice(0, 32);
+  if (found !== SEMBLE_VERSION) throw fault('provider-version-mismatch', 'UNKNOWN', `${python} has semble ${found}; the bridge pins ${SEMBLE_VERSION}`);
+}
+function semanticStatePaths(inventory     )      {
+  const state = path.join(inventory.root, '.doflow', 'index', 'code', 'semble', digest(`${inventory.root}\n${inventory.scopeIgnoreDigest}`));
+  const mirror = path.join(state, 'mirror');
+  const cache = path.join(state, 'cache');
+  return { root: inventory.root, state, mirror, cache, index: path.join(cache, digest(mirror), 'index'),
+    manifest: path.join(state, 'manifest.json'), marker: path.join(state, 'in-progress.json'), lock: path.join(state, 'operation.lock') };
+}
+function inside(root        , file        )          { const rel = path.relative(root, file); return rel === '' || (!rel.startsWith(`..${path.sep}`) && rel !== '..' && !path.isAbsolute(rel)); }
+function safeDirectories(root        , target        , create = false)       {
+  if (!inside(root, target)) throw fault('path-outside-state');
+  let cursor = root;
+  for (const segment of path.relative(root, target).split(path.sep).filter(Boolean)) {
+    cursor = path.join(cursor, segment);
+    try { const st = fs.lstatSync(cursor); if (!st.isDirectory() || st.isSymbolicLink()) throw fault('unsafe-state-directory'); }
+    catch (error     ) { if (error.code !== 'ENOENT' || !create) throw error; fs.mkdirSync(cursor); }
+  }
+}
+function regularBytes(file        , max        )      {
+  const before = fs.lstatSync(file);
+  if (!before.isFile() || before.isSymbolicLink() || before.size > max) throw fault('unsafe-or-oversized-file');
+  const fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+  try {
+    const start = fs.fstatSync(fd);
+    if (start.ino !== before.ino || start.dev !== before.dev) throw fault('source-changed', 'STALE');
+    const buffer = Buffer.alloc(start.size + 1); const count = fs.readSync(fd, buffer, 0, buffer.length, 0);
+    const after = fs.fstatSync(fd);
+    if (count !== start.size || after.size !== start.size || after.mtimeMs !== start.mtimeMs || after.ctimeMs !== start.ctimeMs) throw fault('source-changed', 'STALE');
+    return buffer.subarray(0, count);
+  } finally { fs.closeSync(fd); }
+}
+// `transient` (live provider sinks only) skips entries that vanish mid-walk; `linkRoots` (model only)
+// admits a symlink whose realpath is a regular file inside one of those roots, counted at its target size.
+function scanTree(root        , maxBytes        , maxFiles = 10000, { transient = false, linkRoots = []             } = {})      {
+  if (!fs.lstatSync(root).isDirectory() || fs.lstatSync(root).isSymbolicLink()) throw fault('unsafe-directory');
+  let bytes = 0; let entries = 0; const files        = [];
+  const gone = (error     ) => { if (!transient || error?.code !== 'ENOENT') throw error; };
+  const walk = (dir        ) => {
+    let names           = [];
+    try { names = fs.readdirSync(dir).sort(); } catch (error     ) { gone(error); }
+    for (const name of names) {
+      if (++entries > maxFiles * 4 + 32) throw fault('resource-limit');
+      const full = path.join(dir, name); let st     ; let real                    ;
+      try { st = fs.lstatSync(full); } catch (error     ) { gone(error); continue; }
+      if (st.isSymbolicLink()) {
+        if (!linkRoots.length) throw fault('unsafe-artifact');
+        try { real = fs.realpathSync(full); st = fs.lstatSync(real); } catch { throw fault('unsafe-artifact'); }
+        if (!st.isFile() || !linkRoots.some((r        ) => real !== r && inside(r, real          ))) throw fault('unsafe-artifact');
+      }
+      if (!st.isFile() && !st.isDirectory()) throw fault('unsafe-artifact');
+      if (st.isDirectory()) walk(full);
+      else { bytes += st.size; files.push({ path: path.relative(root, full).split(path.sep).join('/'), sizeBytes: st.size, ...(real ? { real } : {}) });
+        if (bytes > maxBytes || files.length > maxFiles) throw fault('resource-limit'); }
+    }
+  };
+  walk(root); return { bytes, files };
+}
+// Hugging Face snapshot layout only: <hub>/models--<id>/snapshots/<rev>/* link into content-addressed blobs.
+function modelLinkRoots(modelPath        )           {
+  const snapshots = path.dirname(modelPath); const repo = path.dirname(snapshots);
+  if (path.basename(snapshots) !== 'snapshots' || !/^models--[^/\\]+$/.test(path.basename(repo))) return [];
+  return [path.join(repo, 'blobs'), path.join(path.dirname(repo), 'blobs')].filter((dir        ) => {
+    try { return fs.lstatSync(dir).isDirectory() && fs.realpathSync(dir) === dir; } catch { return false; }
+  });
+}
+function inspectModel(modelPath        , limits      = SEMBLE_LIMITS)      {
+  if (typeof modelPath !== 'string' || !path.isAbsolute(modelPath) || fs.realpathSync(modelPath) !== modelPath) throw fault('local-model-required');
+  const inventory = scanTree(modelPath, limits.modelBytes, 10000, { linkRoots: modelLinkRoots(modelPath) });
+  for (const required of ['config.json', 'tokenizer.json', 'model.safetensors']) if (!inventory.files.some((f     ) => f.path === required)) throw fault('local-model-incomplete');
+  const hashes = inventory.files.map((f     ) => [f.path, digest(regularBytes(f.real || path.join(modelPath, f.path), limits.modelBytes))]);
+  return { path: modelPath, identity: digest(JSON.stringify(hashes)), bytes: inventory.bytes };
+}
+function validateInventory(inventory     , limits     )       {
+  if (!inventory?.complete || !path.isAbsolute(inventory.root) || fs.realpathSync(inventory.root) !== inventory.root || !inventory.scopeIgnoreDigest || !inventory.identity) throw fault('incomplete-corpus');
+  if (!Array.isArray(inventory.files) || inventory.files.length > limits.files) throw fault('corpus-limit');
+  const seen = new Set(); let bytes = 0;
+  for (const entry of inventory.files) {
+    if (typeof entry.path !== 'string' || entry.path.includes('\\') || entry.path.split('/').some((p        ) => !p || p === '.' || p === '..') || path.isAbsolute(entry.path) || seen.has(entry.path)) throw fault('unsafe-corpus-path');
+    seen.add(entry.path);
+    if (!/^[0-9a-f]{64}$/.test(entry.fileHash) || entry.sizeBytes > limits.fileBytes || entry.sizeBytes < 0) throw fault('corpus-hash-or-size');
+    bytes += entry.sizeBytes;
+  }
+  if (bytes > limits.sourceBytes) throw fault('corpus-limit');
+}
+function readSource(inventory     , entry     , limits     )      {
+  const absolute = path.join(inventory.root, entry.path);
+  if (entry.absolutePath !== absolute || fs.realpathSync(absolute) !== absolute) throw fault('unsafe-source-path');
+  const data = regularBytes(absolute, limits.fileBytes);
+  if (data.length !== entry.sizeBytes || digest(data) !== entry.fileHash) throw fault('source-changed', 'STALE');
+  return data;
+}
+function checkSources(inventory     , limits     )       {
+  for (const entry of inventory.files) readSource(inventory, entry, limits);
+  // Re-admission detects changed ignore files, scope policy and added/deleted members too.
+  const { fingerprintCorpus } = require('./code-corpus.js');
+  const next = fingerprintCorpus(inventory);
+  if (!next.complete || next.identity !== inventory.identity || next.scopeIgnoreDigest !== inventory.scopeIgnoreDigest) throw fault('corpus-changed', 'STALE');
+}
+// Semble 0.7.0 saves BM25 as `bm25_index/index.npz`: numpy's stored (uncompressed) zip of six 1-D .npy members.
+// Parse it here without NumPy so a garbled, compressed, oversized or inconsistent archive is refused before the loader.
+const BM25_MEMBERS                         = { 'doc_order.npy': '|u1', 'terms.npy': '|u1', 'offsets.npy': '<i8', 'docs.npy': '<i4', 'tfs.npy': '<i4', 'doc_lengths.npy': '<i4' };
+function npzMembers(buffer        )                      {
+  const bad = () => fault('invalid-bm25-archive');
+  const end = buffer.length - 22; // numpy writes no archive comment, so the end record closes the file
+  if (end < 0 || buffer.readUInt32LE(end) !== 0x06054b50) throw bad();
+  const count = buffer.readUInt16LE(end + 10); const size = buffer.readUInt32LE(end + 12); const directory = buffer.readUInt32LE(end + 16); let cursor = directory;
+  if (buffer.readUInt16LE(end + 4) !== 0 || buffer.readUInt16LE(end + 8) !== count || count !== Object.keys(BM25_MEMBERS).length || directory + size !== end) throw bad();
+  const members = new Map                (); let dataEnd = 0;
+  for (let i = 0; i < count; i++) {
+    if (cursor + 46 > end || buffer.readUInt32LE(cursor) !== 0x02014b50) throw bad();
+    const flags = buffer.readUInt16LE(cursor + 8); const method = buffer.readUInt16LE(cursor + 10); const crc = buffer.readUInt32LE(cursor + 16);
+    const stored = buffer.readUInt32LE(cursor + 20); const length = buffer.readUInt32LE(cursor + 24); const local = buffer.readUInt32LE(cursor + 42);
+    const nameLength = buffer.readUInt16LE(cursor + 28); const next = cursor + 46 + nameLength + buffer.readUInt16LE(cursor + 30) + buffer.readUInt16LE(cursor + 32);
+    const name = buffer.subarray(cursor + 46, cursor + 46 + nameLength).toString('latin1');
+    // Stored only: a member can never claim more bytes than the archive holds (no decompression bomb).
+    if (next > end || (flags & 1) || method !== 0 || stored !== length || !(name in BM25_MEMBERS) || members.has(name) || local < dataEnd || local + 30 + nameLength > directory) throw bad();
+    if (buffer.readUInt32LE(local) !== 0x04034b50 || buffer.readUInt16LE(local + 8) !== 0 || buffer.readUInt16LE(local + 26) !== nameLength
+      || buffer.subarray(local + 30, local + 30 + nameLength).toString('latin1') !== name) throw bad();
+    const start = local + 30 + nameLength + buffer.readUInt16LE(local + 28); dataEnd = start + length;
+    if (dataEnd > directory) throw bad();
+    const data = buffer.subarray(start, dataEnd);
+    if (zlib.crc32(data) !== crc) throw bad();
+    members.set(name, data); cursor = next;
+  }
+  if (cursor !== end) throw bad();
+  return members;
+}
+function npyVector(data        , descr        )      {
+  const bad = () => fault('invalid-bm25-archive');
+  if (data.length < 10 || data.subarray(0, 6).toString('hex') !== '934e554d5059' || ![1, 2, 3].includes(data[6]) || data[7] !== 0) throw bad();
+  const start = data[6] === 1 ? 10 : 12; if (data.length < start) throw bad();
+  const headerLength = data[6] === 1 ? data.readUInt16LE(8) : data.readUInt32LE(8);
+  const header = data.subarray(start, start + headerLength).toString('latin1');
+  const shape = /['"]shape['"]\s*:\s*\(\s*(\d+)\s*,\s*\)/.exec(header); const width = +descr.slice(2);
+  if (start + headerLength > data.length || !header.includes(`'descr': '${descr}'`) || !/['"]fortran_order['"]\s*:\s*False/.test(header) || !shape
+    || data.length !== start + headerLength + (+shape[1] * width)) throw bad();
+  const body = data.subarray(start + headerLength); const length = +shape[1];
+  return { length, body, at: (i        ) => (width === 8 ? Number(body.readBigInt64LE(i * 8)) : width === 4 ? body.readInt32LE(i * 4) : body[i]) };
+}
+function unpackStrings(vector     )           {
+  const text = vector.body.toString('utf8');
+  if (vector.length && !text.endsWith('\0')) throw fault('invalid-bm25-archive');
+  return vector.length ? text.slice(0, -1).split('\0') : [];
+}
+// Mirrors Semble 0.7.0 BM25 `_check_consistent` and adds the document count; returns doc_order for the chunk-id cross-check.
+function inspectBm25(buffer        )           {
+  const members = npzMembers(buffer);
+  const v      = Object.fromEntries(Object.entries(BM25_MEMBERS).map(([name, descr]) => [name.slice(0, -4), npyVector(members.get(name)          , descr)]));
+  const docOrder = unpackStrings(v.doc_order); const terms = unpackStrings(v.terms); const n = docOrder.length;
+  let ok = new Set(docOrder).size === n && v.doc_lengths.length === n && v.offsets.length === terms.length + 1 && v.offsets.at(0) === 0
+    && v.offsets.at(v.offsets.length - 1) === v.docs.length && v.tfs.length === v.docs.length;
+  for (let i = 1; ok && i < v.offsets.length; i++) ok = v.offsets.at(i) >= v.offsets.at(i - 1);
+  for (let i = 0; ok && i < v.docs.length; i++) ok = v.docs.at(i) >= 0 && v.docs.at(i) < n;
+  if (!ok) throw fault('inconsistent-bm25-postings');
+  return docOrder;
+}
+function inspectArtifacts(index        , inventory     , paths     , model     , limits     )      {
+  safeDirectories(paths.state, index); safeDirectories(paths.state, paths.mirror);
+  const tree = scanTree(index, limits.artifactBytes, 32);
+  const expected = ['bm25_index/index.npz', 'chunks.json', 'metadata.json', 'semantic_index/arguments.json', 'semantic_index/vectors.npy'];
+  if (JSON.stringify(tree.files.map((f     ) => f.path).sort()) !== JSON.stringify(expected.sort())) throw fault('incomplete-index');
+  const json = (name        ) => JSON.parse(regularBytes(path.join(index, name), limits.artifactBytes).toString('utf8'));
+  const metadata = json('metadata.json'); const chunks = json('chunks.json');
+  if (metadata.root_path !== paths.mirror || metadata.model_path !== model.path || metadata.cache_version !== 2 || metadata.chunk_size !== 750 || JSON.stringify(metadata.content_type) !== '["code"]') throw fault('incompatible-index');
+  if (!Array.isArray(chunks) || chunks.length > limits.chunks) throw fault('invalid-chunk-pool');
+  const docOrder = inspectBm25(regularBytes(path.join(index, 'bm25_index/index.npz'), limits.artifactBytes));
+  if (docOrder.length !== chunks.length) throw fault('invalid-chunk-pool');
+  // Check NPY header without loading NumPy; reject shape/size bombs before its allocator runs.
+  const vectors = regularBytes(path.join(index, 'semantic_index/vectors.npy'), limits.artifactBytes);
+  if (vectors.length < 10 || vectors.subarray(0, 6).toString('hex') !== '934e554d5059' || vectors[6] !== 1 || vectors[7] !== 0) throw fault('invalid-vector-header');
+  const headerLength = vectors.readUInt16LE(8); const header = vectors.subarray(10, 10 + headerLength).toString('ascii');
+  const shape = /['"]shape['"]\s*:\s*\(\s*(\d+)\s*,\s*(\d+)\s*,?\s*\)/.exec(header);
+  const dtype = /['"]descr['"]\s*:\s*['"]([<>=|][fiu])(\d+)['"]/.exec(header);
+  if (!shape || !dtype || +shape[1] !== chunks.length || +shape[2] < 1 || +shape[2] > 65536 || ![1, 2, 4, 8].includes(+dtype[2]) || vectors.length !== 10 + headerLength + (+shape[1] * +shape[2] * +dtype[2])) throw fault('inconsistent-vector-shape');
+  const admitted = new Map(inventory.files.map((e     ) => [e.path, e]));
+  let offset = 0; const ids           = [];
+  for (const [file, value] of Object.entries(metadata.files || {})       ) {
+    if (!admitted.has(file) || !Number.isSafeInteger(value.start) || !Number.isSafeInteger(value.count) || value.start !== offset || value.count < 0 || !Number.isInteger(value.mtime_ns)) throw fault('invalid-index-manifest');
+    for (let slot = 0; slot < value.count; slot++) {
+      const chunk = chunks[offset + slot];
+      if (!chunk || chunk.file_path !== file || !Number.isSafeInteger(chunk.start_line) || !Number.isSafeInteger(chunk.end_line) || chunk.start_line < 1 || chunk.end_line < chunk.start_line) throw fault('unsafe-chunk-path-or-range');
+      ids.push(`${file}:${slot}`);
+    }
+    offset += value.count;
+  }
+  if (offset !== chunks.length || JSON.stringify(ids) !== JSON.stringify(docOrder)) throw fault('inconsistent-artifacts');
+  // All metadata paths are admitted; constructor source reads can never escape this copied mirror.
+  const mirror = scanTree(paths.mirror, limits.sourceBytes, limits.files);
+  if (JSON.stringify(mirror.files.map((f     ) => f.path).sort()) !== JSON.stringify([...admitted.keys()].sort())) throw fault('mirror-membership-mismatch');
+  for (const [file, entry] of admitted       ) if (digest(regularBytes(path.join(paths.mirror, file), limits.fileBytes)) !== entry.fileHash) throw fault('mirror-hash-mismatch', 'STALE');
+  return { chunks: chunks.length, artifactBytes: tree.bytes, artifactIdentity: digest(JSON.stringify(tree.files.map((f     ) => [f.path, digest(regularBytes(path.join(index, f.path), limits.artifactBytes))]))) };
+}
+// The semantic lock records {pid, hostname, token}. A lock whose owner pid is dead on this host (run-lock.ts's liveness
+// rule: process.kill(pid, 0)) is reclaimed under a claim file named for its token, created `wx`: the claim winner re-reads
+// the lock and removes it only while it still carries the judged token, so a live or newer lock is never removed. A lock
+// from another host, from this process, or without a readable record is never reclaimed.
+// Ceiling: a reclaimer killed between creating and removing its claim leaves `operation.lock.claim.<token>`, and that
+// lock then waits for a manual removal, which the contention cause names.
+const LOCK_TOKEN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+function readLockOwner(lock        )      {
+  try {
+    const owner = JSON.parse(regularBytes(lock, 4096).toString('utf8'));
+    return owner && Number.isInteger(owner.pid) && typeof owner.hostname === 'string' && LOCK_TOKEN.test(owner.token) ? owner : null;
+  } catch { return null; }
+}
+function reclaimStaleLock(lock        , owner     , hostname        )          {
+  const claim = `${lock}.claim.${owner.token}`;
+  try { fs.writeFileSync(claim, `${JSON.stringify({ pid: process.pid, hostname })}\n`, { flag: 'wx', mode: 0o600 }); }
+  catch (error     ) { if (error.code === 'EEXIST') return false; throw error; }
+  try {
+    if (readLockOwner(lock)?.token !== owner.token) return false;
+    fs.unlinkSync(lock); return true;
+  } finally { try { fs.unlinkSync(claim); } catch {} }
+}
+async function acquireSemanticLock(paths     , { isAlive = defaultIsAlive, hostname = os.hostname(), waitMs = 100 }      = {})               {
+  safeDirectories(paths.root, paths.state, true);
+  const token = crypto.randomUUID();
+  const deadline = Date.now() + waitMs;
+  while (true) {
+    try {
+      const fd = fs.openSync(paths.lock, 'wx', 0o600); fs.writeFileSync(fd, `${JSON.stringify({ pid: process.pid, hostname, token })}\n`);
+      return () => { fs.closeSync(fd); if (readLockOwner(paths.lock)?.token === token) fs.unlinkSync(paths.lock); };
+    } catch (error     ) { if (error.code !== 'EEXIST') throw error; }
+    const owner = readLockOwner(paths.lock);
+    if (owner && owner.hostname === hostname && owner.pid !== process.pid && !isAlive(owner.pid) && reclaimStaleLock(paths.lock, owner, hostname)) continue;
+    if (Date.now() >= deadline) {
+      throw fault('lock-contention', 'UNKNOWN', `another semantic index operation holds ${paths.lock}${owner ? ` (pid ${owner.pid} on ${owner.hostname})` : ''}; `
+        + 'run the command again when it finishes. A lock whose process has exited on this host is reclaimed automatically; '
+        + `otherwise remove ${paths.lock} (and any ${path.basename(paths.lock)}.claim.* beside it) only after confirming no semantic build, refresh or query is running.`);
+    }
+    await new Promise(resolve => setTimeout(resolve, 10));
+  }
+}
+function cleanupTemporary(paths     )       {
+  for (const name of fs.readdirSync(paths.state)) {
+    if (!/^(query|staging)-[A-Za-z0-9-]+$/.test(name)) continue;
+    const dir = path.join(paths.state, name);
+    scanTree(dir, SEMBLE_LIMITS.artifactBytes, 10000); fs.rmSync(dir, { recursive: true });
+  }
+}
+// Per-invocation disposable sandbox: `stats/` is Semble's statistics sink (query SEMBLE_CACHE_LOCATION, 64 KiB);
+// `library/` takes every redirected library cache/temp location. Semble 0.7.0 (semble-grammars 0.1.2) extracts sha-verified tree-sitter
+// grammars from its own bundled archive there (77 libraries, 79.6 MB uncompressed on macos-arm64), so it is
+// bounded by `libraryBytes` instead of the statistics cap.
+function bridgeSandbox(sandbox        )      {
+  const temp = path.join(sandbox, 'stats'); const library = path.join(sandbox, 'library');
+  for (const dir of [temp, library]) if (!fs.existsSync(dir)) fs.mkdirSync(dir);
+  return { temp, library };
+}
+function checkSandbox(sinks     , limits     , transient = false)       {
+  scanTree(sinks.temp, limits.statsBytes, 128, { transient });
+  scanTree(sinks.library, limits.libraryBytes, 512, { transient });
+}
+function executeBridge(request     , options     , paths     , sandbox        )               {
+  const limits = options.limits; const deadline = request.action === 'query' ? limits.queryMs : limits.lifecycleMs;
+  const sinks = bridgeSandbox(sandbox); const { temp, library } = sinks;
+  return new Promise(resolve => {
+    const env = { ...process.env, PYTHONDONTWRITEBYTECODE: '1', PYTHONHASHSEED: '0', OMP_NUM_THREADS: '1', OPENBLAS_NUM_THREADS: '1', MKL_NUM_THREADS: '1', HF_HUB_OFFLINE: '1', TRANSFORMERS_OFFLINE: '1', HF_DATASETS_OFFLINE: '1',
+      SEMBLE_CACHE_LOCATION: request.action === 'query' ? temp : paths.cache, HF_HOME: library, HUGGINGFACE_HUB_CACHE: library,
+      TRANSFORMERS_CACHE: library, XDG_CACHE_HOME: library, SEMBLE_GRAMMARS_CACHE_DIR: path.join(library, 'grammars'), TORCH_HOME: library,
+      TMPDIR: library, TEMP: library, TMP: library, TOKENIZERS_PARALLELISM: 'false', SEMBLE_INDEX_WORKERS: '0' };
+    const child = spawn(options.python, [options.bridgePath || path.join(__dirname, 'semble-bridge.py')], { cwd: paths.state, env, stdio: ['pipe', 'pipe', 'pipe'], shell: false });
+    let stdout = ''; let outputBytes = 0; let failure                = null; let done = false;
+    const stop = (reason        ) => { if (!failure) failure = reason; child.kill('SIGKILL'); };
+    const timer = setTimeout(() => stop('provider-timeout'), deadline);
+    // A live child creates and removes files while we walk; only a real overrun is a resource limit.
+    const sandboxFault = (error     ) => error?.reason === 'resource-limit' ? 'provider-resource-limit' : 'provider-unsafe-write';
+    const poll = setInterval(() => { try { checkSandbox(sinks, limits, true); if (request.savePath && fs.existsSync(request.savePath)) scanTree(request.savePath, limits.artifactBytes, 32, { transient: true }); } catch (error     ) { stop(sandboxFault(error)); } }, 10);
+    const finish = (result     ) => { if (done) return; done = true; clearTimeout(timer); clearInterval(poll); resolve(result); };
+    child.stdout.on('data', (chunk     ) => { outputBytes += chunk.length; if (outputBytes > limits.outputBytes) stop('provider-output-limit'); else stdout += chunk.toString('utf8'); });
+    child.stderr.on('data', (chunk     ) => { outputBytes += chunk.length; if (outputBytes > limits.outputBytes) stop('provider-output-limit'); });
+    child.on('error', () => finish({ ok: false, reason: 'provider-unavailable' }));
+    child.on('close', (code        ) => {
+      if (failure) return finish({ ok: false, reason: failure });
+      try { checkSandbox(sinks, limits); } catch (error     ) { return finish({ ok: false, reason: sandboxFault(error) }); }
+      if (code !== 0) return finish({ ok: false, reason: 'provider-error' });
+      try { const result = JSON.parse(stdout); if (result.version !== SEMBLE_VERSION || typeof result.ok !== 'boolean') throw Error(); finish(result); }
+      catch { finish({ ok: false, reason: 'invalid-provider-output' }); }
+    });
+    child.stdin.on('error', () => {}); child.stdin.end(JSON.stringify(request));
+  });
+}
+function readCompleted(paths     , inventory     , model     , limits     , allowChanged = false)      {
+  if (fs.existsSync(paths.marker)) throw fault('index-in-progress');
+  let manifest     ;
+  try { manifest = JSON.parse(regularBytes(paths.manifest, 2097152).toString('utf8')); } catch { throw fault('index-missing-or-corrupt'); }
+  if (manifest.schemaVersion !== 1 || manifest.complete !== true || !manifest.generation || !manifest.artifactIdentity) throw fault('unknown-index-identity');
+  if (manifest.root !== inventory.root || manifest.scopeIgnoreDigest !== inventory.scopeIgnoreDigest || manifest.providerVersion !== SEMBLE_VERSION || manifest.model?.identity !== model.identity || manifest.model?.path !== model.path) throw fault('index-identity-mismatch', 'STALE');
+  if (!allowChanged && manifest.corpusIdentity !== inventory.identity) throw fault('index-source-mismatch', 'STALE');
+  return manifest;
+}
+async function runSembleQuery(options     )               {
+  const limits = { ...SEMBLE_LIMITS, ...options.limits }; const inventory = options.inventory;
+  let release     ; let temp                    ;
+  try {
+    validateInventory(inventory, limits); const model = inspectModel(options.modelPath, limits); const paths = semanticStatePaths(inventory);
+    const python = options.python || resolveSembleInterpreter().python;
+    release = await acquireSemanticLock(paths); cleanupTemporary(paths);
+    const manifest = readCompleted(paths, inventory, model, limits);
+    checkSources(inventory, limits);
+    const artifacts = inspectArtifacts(paths.index, inventory, paths, model, limits);
+    if (artifacts.artifactIdentity !== manifest.artifactIdentity) throw fault('index-artifacts-changed');
+    const queryTemp         = fs.mkdtempSync(path.join(paths.state, 'query-')); temp = queryTemp;
+    const result = await executeBridge({ action: 'query', query: options.query, indexPath: paths.index, modelPath: model.path,
+      poolSize: artifacts.chunks, allowedWriteRoots: [queryTemp] }, { ...options, python, limits }, paths, queryTemp);
+    if (!result.ok) throw fault(result.reason || 'provider-error', 'UNKNOWN', typeof result.cause === 'string' ? result.cause : undefined);
+    if (!result.runtimeIdentity || JSON.stringify(result.runtimeIdentity) !== JSON.stringify(manifest.runtimeIdentity)) throw fault('provider-runtime-identity-mismatch', 'STALE');
+    if (!Array.isArray(result.candidates) || result.candidates.length > 200) throw fault('invalid-provider-output');
+    const admitted = new Map(inventory.files.map((f     ) => [f.path, f]));
+    for (const candidate of result.candidates) {
+      const loc = candidate.locator;
+      if (!loc || !admitted.has(loc.file) || !Number.isSafeInteger(loc.line) || !Number.isSafeInteger(loc.endLine) || loc.line < 1 || loc.endLine < loc.line || !Number.isFinite(candidate.score)) throw fault('invalid-provider-candidate');
+      candidate.indexedSourceIdentity = (admitted.get(loc.file)       ).fileHash;
+    }
+    checkSources(inventory, limits);
+    if (inspectModel(options.modelPath, limits).identity !== model.identity) throw fault('model-changed', 'STALE');
+    // sourceReadBytes is the admitted corpus size; Semble 0.7.0's loader only stats sources, so it over-counts provider reads.
+    return { ok: true, provider: 'semble.search', version: SEMBLE_VERSION, model, generation: manifest.generation, freshness: 'FRESH', candidates: result.candidates,
+      accounting: { indexedChunks: artifacts.chunks, sourceReadBytes: inventory.files.reduce((n        , f     ) => n + f.sizeBytes, 0), artifactBytes: artifacts.artifactBytes } };
+  } catch (error     ) { return { ok: false, provider: 'semble.search', version: SEMBLE_VERSION, freshness: error.freshness || 'UNKNOWN', reason: error.reason || 'provider-unavailable',
+    ...(typeof error.cause === 'string' ? { cause: error.cause } : {}), candidates: [] }; }
+  finally { try { if (temp) fs.rmSync(temp, { recursive: true, force: true }); } catch {} try { if (release) release(); } catch {} }
+}
+module.exports = { SEMBLE_VERSION, SEMBLE_LIMITS, runSembleQuery, resolveSembleInterpreter, checkSembleVersion, semanticStatePaths, digest, fault, inside, safeDirectories,
+  regularBytes, scanTree, inspectModel, inspectBm25, validateInventory, readSource, checkSources, inspectArtifacts, acquireSemanticLock, cleanupTemporary, executeBridge, readCompleted, modelLinkRoots };

package/src/runtime/lifecycle/cli.js

@@ -15,7 +15,8 @@ const followup = require('./followup.js');
 const { StoreUnsafeError, StoreLockedError } = require('./event-store.js');
 const { prepareStore } = require('./store-upkeep.js');
 const { printSafe } = require('../mask.js');
-const { buildOverview, initFeature, featureStatus } = require('./overview.js');
+const { buildOverview, initFeature, featureStatus, activeFeature } = require('./overview.js');
+const { recordFeature, clearSlug } = require('../feature-pointer.js');
 const { releaseFeatures, recordMerged } = require('./release.js');
 const goal = require('./goal.js');
 
@@ -92,7 +93,9 @@ function releaseLines(r     ) {
 function lifecycleLines(result     ) {
   switch (result.action) {
     case 'init': return [`${result.slug}: tracked ${result.tracked}${result.taken.length ? `, took ${result.taken.join(', ')}` : ''}${result.goal ? `, serves ${result.goal}` : ''}`, ...result.next];
-    case 'status': return [`${result.slug}: ${result.status}${result.evidence ? ` (${result.evidence.kind}${result.evidence.ref ? ` ${result.evidence.ref}` : ''})` : ''}${result.release ? `, release ${result.release}` : ''}`, ...(result.note ? [`note: ${result.note}`] : [])];
+    case 'status':
+      if (result.active) return [result.slug && result.status ? `${result.slug}: ${result.status}${result.evidence ? ` (${result.evidence.kind}${result.evidence.ref ? ` ${result.evidence.ref}` : ''})` : ''}${result.release ? `, release ${result.release}` : ''}` : result.message, ...(result.active.state === 'agree' ? [`pointer agrees with branch ${result.active.branch}${result.active.artifactDir ? `, artifacts in ${result.active.artifactDir}` : ''}`] : [])];
+      return [`${result.slug}: ${result.status}${result.evidence ? ` (${result.evidence.kind}${result.evidence.ref ? ` ${result.evidence.ref}` : ''})` : ''}${result.release ? `, release ${result.release}` : ''}`, ...(result.note ? [`note: ${result.note}`] : [])];
     case 'release': return releaseLines(result);
     case 'merged': return [`${result.slug}: merge confirmed, now ${result.status}`];
     default: return result.mode ? overviewLines(result) : [];
@@ -233,10 +236,17 @@ function handleLifecycleCommand({ action, cwd, global = false, slug = null, json
     if (refusedStore) return emit(refusedStore, json, lifecycleLines);
     let result;
     if (act === 'overview') result = buildOverview({ root, maintain: Boolean(flags.maintain), since: flags.since });
-    else if (act === 'init') result = initFeature({ root, slug, take: flags.take, intent: flags.intent, goal: flags.goal });
-    else if (act === 'release') result = releaseFeatures({ root, tag: flags.tag, confirm: Boolean(flags.confirm), features: flags.feature, exclude: flags.exclude, channel: flags.channel });
-    else if (act === 'merged') result = recordMerged({ root, slug, reason: flags.reason, channel: flags.channel });
-    else result = featureStatus({ root, slug });
+    else if (act === 'init') {
+      result = initFeature({ root, slug, take: flags.take, intent: flags.intent, goal: flags.goal });
+      if (result.ok) recordFeature({ storeRoot: root, cwd: cwd || process.cwd(), slug });
+    }
+    else if (act === 'release') {
+      result = releaseFeatures({ root, tag: flags.tag, confirm: Boolean(flags.confirm), features: flags.feature, exclude: flags.exclude, channel: flags.channel });
+      if (result.ok && result.recorded) for (const shipped of [...result.candidates.map((c     ) => c.slug), ...result.added]) if (!result.excluded.includes(shipped)) clearSlug({ storeRoot: root, slug: shipped });
+    } else if (act === 'merged') {
+      result = recordMerged({ root, slug, reason: flags.reason, channel: flags.channel });
+      if (result.ok || result.finding === 'already-merged') clearSlug({ storeRoot: root, slug });
+    } else result = slug ? featureStatus({ root, slug }) : activeFeature({ root, cwd: cwd || process.cwd() });
     return emit(result, json, lifecycleLines);
   });
 }

package/src/runtime/lifecycle/event-store.js

@@ -39,12 +39,12 @@ const MAX_EVENT_BYTES = 256 * 1024;
 const MAX_JOURNAL_BYTES = 16 * 1024 * 1024;
 const READ_CHUNK = 64 * 1024;
 /** The decision register's channel vocabulary: who the caller says is acting. */
-const CHANNEL_BY                         = { question: 'user', gate: 'user', prompt: 'user', default: 'agent' };
+const CHANNEL_BY                         = { question: 'user', gate: 'user', prompt: 'user', default: 'agent', resolution: 'agent', policy: 'autopilot' };
 
 function eventsDir(root        )         { return path.join(root, EVENTS_REL); }
 function lockTarget(root        )         { return path.join(root, EVENTS_REL); }
 
-/** @param {string} [channel] defaults to `default` @returns {'user'|'agent'|null} null for an unknown channel */
+/** @param {string} [channel] defaults to `default` @returns {'user'|'agent'|'autopilot'|null} null for an unknown channel */
 function byFromChannel(channel         = 'default')                { return CHANNEL_BY[channel] ?? null; }
 
 /** `length` random characters of the lowercase Crockford base32 alphabet. */
@@ -235,13 +235,15 @@ function readEvents(root        , { fsImpl = nodeFs, lockFallback = true, should
 }
 
 /**
- * Reads and folds the store.
+ * Reads and folds the store. With `DOFLOW_UPKEEP=off` in `env` the read never falls back to the
+ * store lock (it would make `events.lock`, a write the switch promises not to make): a journal that
+ * keeps moving during the read throws StoreLockedError instead.
  * @param {string} root the IC-001 root
- * @param {{hasBody?: Function, fsImpl?: Object}} [options]
+ * @param {{hasBody?: Function, fsImpl?: Object, now?: Date, env?: Object}} [options]
  * @returns {Object} the fold result (see fold.js) plus `unreadable`
  */
-function readFold(root        , { fsImpl = nodeFs, hasBody, now = new Date() }      = {})      {
-  const { events, unreadable, reasons } = readEvents(root, { fsImpl });
+function readFold(root        , { fsImpl = nodeFs, hasBody, now = new Date(), env = process.env }      = {})      {
+  const { events, unreadable, reasons } = readEvents(root, { fsImpl, lockFallback: env.DOFLOW_UPKEEP !== 'off' });
   return { ...finalize(foldInto(events, { now }), { hasBody }), unreadable, unreadableReasons: reasons };
 }
 

package/src/runtime/lifecycle/followup.js

@@ -73,7 +73,7 @@ function newFollowupId(taken     ) {
 
 function channelBy(channel     ) {
   const by = byFromChannel(channel || 'default');
-  if (!by) throw new FollowupUsageError(`unknown --channel '${channel}'. Valid: question, gate, prompt, default`);
+  if (!by) throw new FollowupUsageError(`unknown --channel '${channel}'. Valid: question, gate, prompt, resolution, default`);
   return by;
 }
 
@@ -350,6 +350,11 @@ function takeFollowups({ root, ids, slug, channel, now = new Date(), fsImpl = no
   if (!slug) throw new FollowupUsageError('--slug is required for --action take');
   const bad = invalidSlugRefusal(slug);
   if (bad) throw new FollowupUsageError(bad.message);
+  // `list` shows a taken item whose feature finished as `done`, but the fold still holds it `taken`: say what the user was shown.
+  const shown = loadFollowups(root, { fsImpl, now }).followups.find((item     ) => item.derived && list.includes(item.id));
+  if (shown) {
+    return refusal('take', 'illegal-transition', `${shown.id} is done because feature ${shown.takenBy} finished (derived from git and the release records, not recorded on the item); only an open item can be taken. Nothing was written.`);
+  }
   const out = appendEvents(root, [{ type: 'followup.taken', by: channelBy(channel), data: { ids: list, feature: slug } }], { now, fsImpl });
   if (!out.ok) return refusalFrom('take', out);
   return { ok: true, action: 'take', ids: list, feature: slug, events: out.written.map((w     ) => w.file), next: [] };

package/src/runtime/lifecycle/overview.js

@@ -16,6 +16,7 @@ const { withDerivedDone } = require('./fold.js');
 const { appendEvents, readFold, readEvents } = require('./event-store.js');
 const { deriveStatuses, bucketize, behindNote } = require('./status.js');
 const { FollowupUsageError, parseIds } = require('./followup.js');
+const { describeActive } = require('../feature-pointer.js');
 
 /** The failure store, or null when its module cannot be loaded: the overview then reports no failures. */
 function failureStoreOrNull() {
@@ -289,4 +290,26 @@ function featureStatus({ root, slug, now = new Date(), fsImpl = nodeFs }     ) {
   return result;
 }
 
-module.exports = { buildOverview, initFeature, featureStatus, goalView, goalConflicts, goalConflictNext, DISCOVERY_SHOWN, MAINTAIN_SHOWN, FEATURES_SHOWN };
+/**
+ * `status` with no `--slug` (row 135): the feature the runtime recorded for this checkout, against the
+ * branch's. A mismatch or an unreadable pointer is a refusal (exit 1) that names both sides and picks
+ * neither; an agreeing pointer also carries the tracked feature's derived status, as `--slug` does.
+ */
+function activeFeature({ root, cwd, now = new Date(), fsImpl = nodeFs }     ) {
+  const active = describeActive({ storeRoot: root, cwd });
+  const here = `branch ${active.current.branch || 'unknown'}${active.current.slug ? `, branch feature ${active.current.slug}` : ''}`;
+  if (active.state === 'unreadable') {
+    return { ok: false, action: 'status', finding: 'feature-pointer-unreadable', message: `${active.file} cannot be read (${active.reason}); delete it to let the next feature start write it again.`, active };
+  }
+  if (active.state === 'mismatch') {
+    const p = active.pointer;
+    return { ok: false, action: 'status', finding: 'feature-mismatch', message: `the pointer names ${p.slug} on branch ${p.branch || 'unknown'}, but this checkout is on ${here}; neither is trusted, so check which feature you are on.`, active };
+  }
+  const result      = { ok: true, action: 'status', active };
+  if (active.state === 'none') return { ...result, message: `no active feature is recorded for this checkout (${here}); pass --slug <slug> to ask about one.` };
+  // An untracked feature is refused by featureStatus; the pointer answer stands, named, without status fields.
+  const derived = featureStatus({ root, slug: active.slug, now, fsImpl });
+  return derived.ok ? { ...derived, active } : { ...result, slug: active.slug, message: `${active.slug} is tracked by its run only; \`lifecycle --action init\` to track it.` };
+}
+
+module.exports = { buildOverview, initFeature, featureStatus, activeFeature, goalView, goalConflicts, goalConflictNext, DISCOVERY_SHOWN, MAINTAIN_SHOWN, FEATURES_SHOWN };

package/src/runtime/lifecycle/report-store.js

@@ -6,7 +6,7 @@
  * The machine-local report body (IC-005, DEC-014). A report's text can hold a crash trace, a log or
  * pasted output, so it never enters the repository: the body is masked with the body profile (IC-012),
  * cut to at most 1 MiB and written once under the same per-machine home the failure store uses,
- * `<XDG_CONFIG_HOME or $HOME/.config>/doflow/reports/<projectKey>/<FU-id>.txt`, folder 0700 and file
+ * `<config home>/doflow/reports/<projectKey>/<FU-id>.txt`, folder 0700 and file
  * 0600. The project event carries only a reference, the size and a masked 2 KB excerpt.
  *
  * `projectKey` is the first 12 hex characters of the SHA-256 of the IC-001 root's real path, so two
@@ -20,6 +20,7 @@ const nodeFs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
 const mask = require('../mask.js');
+const { configHome } = require('../config-home.js');
 
 /** A `--file` or `--stdin` source is read for at most this many bytes; the rest could not be kept anyway. */
 const MAX_READ_BYTES = 16 * 1024 * 1024;
@@ -38,17 +39,14 @@ const EXCERPT_BYTES = 2048;
 class ReportInputError extends Error {}
 
 /**
- * The folder holding every project's report bodies, or null when no home resolves. It resolves the
- * base the way IC-011 resolves the failure home (`XDG_CONFIG_HOME` when set, non-empty and absolute,
- * else `$HOME/.config` when `HOME` is absolute) and sits beside it, `doflow/reports`. The rule is
- * repeated here rather than required from the failure module, so the follow-up service still loads in
- * a build or an install where the failure modules cannot be loaded (IC-016).
+ * The folder holding every project's report bodies, or null when no config home resolves. It sits in
+ * the same config home as the failure home (`../config-home.js`), `doflow/reports`, and takes that
+ * leaf helper rather than the failure module, so the follow-up service still loads in a build or an
+ * install where the failure modules cannot be loaded (IC-016).
  */
 function reportsHome(env                                     = process.env)                {
-  const xdg = env.XDG_CONFIG_HOME;
-  if (typeof xdg === 'string' && xdg !== '') return path.isAbsolute(xdg) ? path.join(xdg, 'doflow', 'reports') : null;
-  const home = env.HOME;
-  return typeof home === 'string' && path.isAbsolute(home) ? path.join(home, '.config', 'doflow', 'reports') : null;
+  const { dir } = configHome(env);
+  return dir === null ? null : path.join(dir, 'reports');
 }
 
 function realProjectRoot(root        , fsImpl      = nodeFs)         {