atris 3.71.2 → 3.72.0

package/lib/mission-code-provenance.js

@@ -0,0 +1,118 @@
+'use strict';
+
+const fs = require('fs');
+const { devNull } = require('os');
+const { spawnSync } = require('child_process');
+
+const BASELINE_SCHEMA = 'atris.mission_code_baseline.v1';
+const PROVENANCE_SCHEMA = 'atris.mission_code_provenance.v1';
+const BOOKKEEPING = ['.atris/', 'atris/runs/', 'atris/status/'];
+
+function fail(reason) {
+  throw new Error(reason);
+}
+
+function git(root, args, reason = 'git_command_failed') {
+  // Disabling replacements alone still permits info/grafts and inherited graft
+  // files to rewrite ancestry. Evidence needs the actual commit relationships.
+  const env = { ...process.env, GIT_NO_REPLACE_OBJECTS: '1', GIT_GRAFT_FILE: devNull };
+  // Evidence belongs to this on-disk repository, even when the caller was
+  // launched by a Git hook with another index or repository in its environment.
+  for (const key of ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_COMMON_DIR', 'GIT_INDEX_FILE', 'GIT_OBJECT_DIRECTORY', 'GIT_ALTERNATE_OBJECT_DIRECTORIES', 'GIT_NAMESPACE', 'GIT_SHALLOW_FILE']) delete env[key];
+  const result = spawnSync('git', ['-c', 'core.fsmonitor=false', ...args], {
+    cwd: root, env, timeout: 15000, maxBuffer: Infinity,
+  });
+  if (result.error || result.status !== 0 || !Buffer.isBuffer(result.stdout)) fail(reason);
+  const text = result.stdout.toString('utf8');
+  // A lossy filename decode cannot stand in for a complete path list.
+  if (!Buffer.from(text, 'utf8').equals(result.stdout)) fail('git_output_unreadable');
+  return text;
+}
+
+function repositoryRoot(root) {
+  const physical = fs.realpathSync(root);
+  const top = git(physical, ['rev-parse', '--show-toplevel'], 'not_git_repository').replace(/\n$/, '');
+  if (fs.realpathSync(top) !== physical) fail('root_not_git_top_level');
+  return physical;
+}
+
+function nulEntries(text) {
+  if (!text) return [];
+  if (!text.endsWith('\0')) fail('git_output_incomplete');
+  return text.slice(0, -1).split('\0');
+}
+
+function knownCommit(root, commit) {
+  if (typeof commit !== 'string' || !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(commit)) fail('commit_unavailable');
+  if (git(root, ['cat-file', '-t', commit], 'commit_unavailable').trim() !== 'commit') fail('commit_unavailable');
+  return commit;
+}
+
+function cleanHead(root) {
+  const head = knownCommit(root, git(root, ['rev-parse', '--verify', 'HEAD'], 'head_unavailable').trim());
+  // Disabling rename detection exposes both paths, including a product file
+  // moved into a bookkeeping directory. Every untracked file is inspected.
+  const entries = nulEntries(git(root, [
+    'status', '--porcelain=v1', '-z', '--untracked-files=all', '--no-renames', '--ignore-submodules=none',
+  ], 'git_status_unavailable'));
+  for (const entry of entries) {
+    if (entry.length < 4 || entry[2] !== ' ') fail('git_status_unreadable');
+    if (!BOOKKEEPING.some((prefix) => entry.slice(3).startsWith(prefix))) fail('product_dirty');
+  }
+  if (git(root, ['rev-parse', '--verify', 'HEAD'], 'head_unavailable').trim() !== head) fail('head_changed_during_capture');
+  return head;
+}
+
+function committedFiles(root, base, head) {
+  knownCommit(root, base);
+  knownCommit(root, head);
+  git(root, ['merge-base', '--is-ancestor', base, head], 'base_not_ancestor');
+  // No sample, path filter, or rename folding: deleted and renamed source
+  // paths matter as much as additions, including committed bookkeeping.
+  return nulEntries(git(root, [
+    'diff', '--name-only', '--no-renames', '--no-ext-diff', '--no-textconv', '-z', base, head, '--',
+  ], 'git_diff_unavailable'));
+}
+
+function unavailable(schema, error) {
+  return { schema, status: 'unavailable', reason: error?.message || 'git_evidence_unavailable' };
+}
+
+function captureCodeBaseline(root) {
+  try {
+    const repo_root = repositoryRoot(root);
+    return { schema: BASELINE_SCHEMA, status: 'complete', repo_root, base_commit: cleanHead(repo_root) };
+  } catch (error) {
+    return unavailable(BASELINE_SCHEMA, error);
+  }
+}
+
+function collectCodeProvenance(root, baseline) {
+  try {
+    if (baseline?.schema !== BASELINE_SCHEMA || baseline.status !== 'complete') fail('baseline_unavailable');
+    const repo_root = repositoryRoot(root);
+    if (baseline.repo_root !== repo_root) fail('baseline_repository_mismatch');
+    const head_commit = cleanHead(repo_root);
+    const base_commit = baseline.base_commit;
+    const files = committedFiles(repo_root, base_commit, head_commit);
+    return { schema: PROVENANCE_SCHEMA, status: 'complete', repo_root, base_commit, head_commit, files };
+  } catch (error) {
+    return unavailable(PROVENANCE_SCHEMA, error);
+  }
+}
+
+function verifyCodeProvenance(root, provenance) {
+  try {
+    if (provenance?.schema !== PROVENANCE_SCHEMA || provenance.status !== 'complete' || !Array.isArray(provenance.files)) fail('provenance_unavailable');
+    const repo_root = repositoryRoot(root);
+    if (provenance.repo_root !== repo_root) fail('provenance_repository_mismatch');
+    // Historical evidence stays valid when the current checkout moves on.
+    const actual = committedFiles(repo_root, provenance.base_commit, provenance.head_commit);
+    if (actual.length !== provenance.files.length || actual.some((file, index) => file !== provenance.files[index])) fail('provenance_files_mismatch');
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, reason: error?.message || 'git_evidence_unavailable' };
+  }
+}
+
+module.exports = { captureCodeBaseline, collectCodeProvenance, verifyCodeProvenance };

package/lib/mission-protected-lane.js

@@ -235,11 +235,53 @@ function gitSubcommand(args) {
   return '';
 }
 
+// Tools that can publish, post, send, or merge. With a mission id, each one
+// found on PATH gets a wrapper that checks the mission's your-yes lock first
+// (lib/yes-lock.js); with no lock file the wrapper just runs the tool.
+const YES_LOCK_TOOLS = ['npm', 'yarn', 'pnpm', 'npx', 'pnpx', 'bunx', 'gh', 'atris'];
+
+// The lines every wrapper shares: ask the lock, refuse with its message, run
+// the real tool, and close the steps a yes allowed once that run succeeds.
+function yesLockLines(toolExpr, binExpr) {
+  return [
+    `const yesLock = require(${JSON.stringify(path.join(__dirname, 'yes-lock.js'))});`,
+    `const verdict = config.missionId ? yesLock.check({ stateDir: config.stateDir, missionId: config.missionId, seal: config.seal, tool: ${toolExpr}, args, gitBin: config.gitBin || null, cwd: process.cwd(), env: process.env }) : null;`,
+    `if (verdict && verdict.hold) { process.stderr.write(verdict.message + '\\n'); process.exit(yesLock.HELD_EXIT); }`,
+    `const runReal = () => { const child = spawnSync(${binExpr}, args, { cwd: process.cwd(), stdio: 'inherit' }); const ok = !child.error && child.status === 0; if (verdict && verdict.consume) yesLock.consume(config.stateDir, config.missionId, config.seal, verdict.consume, { ok, claims: verdict.claims }); if (child.error) { process.stderr.write(child.error.message + '\\n'); process.exit(1); } process.exit(child.status == null ? 1 : child.status); };`,
+  ];
+}
+
+function resolveTool(name, root, pathValue) {
+  const found = spawnSync('sh', ['-c', `command -v ${name}`], { cwd: root, encoding: 'utf8', timeout: 5000, env: { ...process.env, PATH: pathValue } });
+  const bin = String(found.stdout || '').trim();
+  return found.status === 0 && bin && path.isAbsolute(bin) ? bin : null;
+}
+
+function yesLockWrapper({ tool, realBin, missionId, seal, stateDir }) {
+  const config = { tool, realBin, missionId, seal, stateDir };
+  return [
+    '#!/usr/bin/env node',
+    "'use strict';",
+    `const { spawnSync } = require('child_process');`,
+    `const config = ${JSON.stringify(config)};`,
+    `const args = process.argv.slice(2);`,
+    ...yesLockLines('config.tool', 'config.realBin'),
+    'runReal();',
+    '',
+  ].join('\n');
+}
+
 function prepareMissionGitGuard({
   root = process.cwd(),
   tags = [],
   pathValue = process.env.PATH || '',
+  missionId = null,
+  // the sealed owner steps from the mission record, and where approvals live
+  yesLockSeal = [],
+  stateDir = null,
 } = {}) {
+  const seal = Array.isArray(yesLockSeal) ? yesLockSeal : [];
+  const locked = Boolean(missionId && seal.length && stateDir);
   const resolved = spawnSync('sh', ['-c', 'command -v git'], {
     cwd: root,
     encoding: 'utf8',
@@ -253,7 +295,7 @@ function prepareMissionGitGuard({
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'atris-mission-git-'));
   const wrapper = path.join(dir, 'git');
   const modulePath = __filename;
-  const config = { root: path.resolve(root), tags: normalizedTags(tags), gitBin };
+  const config = { root: path.resolve(root), tags: normalizedTags(tags), gitBin, missionId: locked ? missionId : null, seal, stateDir };
   const source = [
     '#!/usr/bin/env node',
     "'use strict';",
@@ -263,6 +305,7 @@ function prepareMissionGitGuard({
     gitSubcommand.toString(),
     defaultGit.toString(),
     `const args = process.argv.slice(2);`,
+    ...yesLockLines("'git'", 'config.gitBin'),
     `if (gitSubcommand(args) === 'commit') {`,
     `  const result = guard.inspectMissionProtectedDiff({ root: config.root, tags: config.tags, includeUnstaged: false, git: defaultGit(config.gitBin) });`,
     `  if (!result.allowed) {`,
@@ -270,12 +313,17 @@ function prepareMissionGitGuard({
     `    process.exit(78);`,
     `  }`,
     `}`,
-    `const child = spawnSync(config.gitBin, args, { cwd: process.cwd(), stdio: 'inherit' });`,
-    `if (child.error) { process.stderr.write(child.error.message + '\\n'); process.exit(1); }`,
-    `process.exit(child.status == null ? 1 : child.status);`,
+    'runReal();',
     '',
   ].join('\n');
   fs.writeFileSync(wrapper, source, { encoding: 'utf8', mode: 0o755 });
+  if (locked) {
+    for (const tool of YES_LOCK_TOOLS) {
+      const realBin = resolveTool(tool, root, pathValue);
+      if (!realBin) continue;
+      fs.writeFileSync(path.join(dir, tool), yesLockWrapper({ tool, realBin, missionId, seal, stateDir }), { encoding: 'utf8', mode: 0o755 });
+    }
+  }
 
   return {
     env: { ...process.env, PATH: `${dir}${path.delimiter}${pathValue}` },

package/lib/pulse.js

@@ -603,6 +603,7 @@ function buildTickScript(opts = {}) {
     pathDirs = [],
     launchLabel = '',
     launchPlistPath = '',
+    tickFlags = [],
   } = opts;
   if (!root) throw new Error('buildTickScript: root is required');
   if (!stateHome) throw new Error('buildTickScript: stateHome is required');
@@ -690,7 +691,7 @@ ${runnerBinExport}
 ${runnerCommandTemplateExport}
 export ATRIS_SKIP_UPDATE_CHECK=1
 
-"$ATRIS" pulse tick --json${safeVerify == null ? '' : ` --verify '${safeVerify}'`} >> "$log" 2>&1
+"$ATRIS" pulse tick --json${tickFlags.filter((f) => /^--[a-z-]+$/.test(f)).map((f) => ` ${f}`).join('')}${safeVerify == null ? '' : ` --verify '${safeVerify}'`} >> "$log" 2>&1
 tick_status=$?
 
 # runDaily no-ops via last_run_date after the first daily run.

package/lib/qr.js

@@ -0,0 +1,338 @@
+'use strict';
+
+// A small QR code encoder: byte mode, error correction level M, versions 1
+// to 10 (up to 213 bytes, plenty for a link). Follows the QR spec (ISO 18004)
+// the same way most small encoders do: pick the smallest version that fits,
+// add Reed-Solomon error correction per block, interleave, place the bits,
+// then try all eight masks and keep the one with the lowest penalty.
+//
+// encodeQr(text) -> { version, size, mask, modules } where modules[y][x] is
+// true for a dark square. qrLines(text) renders it for a terminal with half
+// block characters, two rows of squares per line, quiet zone included.
+
+const MAX_VERSION = 10;
+// Level M tables, index = version (index 0 unused).
+const ECC_PER_BLOCK = [-1, 10, 16, 26, 18, 24, 16, 18, 22, 22, 26];
+const ECC_BLOCKS = [-1, 1, 1, 1, 2, 2, 4, 4, 4, 5, 5];
+const FORMAT_BITS_M = 0;
+
+function rawDataModules(ver) {
+  let result = (16 * ver + 128) * ver + 64;
+  if (ver >= 2) {
+    const numAlign = Math.floor(ver / 7) + 2;
+    result -= (25 * numAlign - 10) * numAlign - 55;
+    if (ver >= 7) result -= 36;
+  }
+  return result;
+}
+
+function dataCodewords(ver) {
+  return Math.floor(rawDataModules(ver) / 8) - ECC_PER_BLOCK[ver] * ECC_BLOCKS[ver];
+}
+
+// Multiply in GF(2^8) with the QR polynomial x^8 + x^4 + x^3 + x^2 + 1.
+function gfMul(x, y) {
+  let z = 0;
+  for (let i = 7; i >= 0; i -= 1) {
+    z = (z << 1) ^ ((z >>> 7) * 0x11d);
+    z ^= ((y >>> i) & 1) * x;
+  }
+  return z & 0xff;
+}
+
+function rsDivisor(degree) {
+  const result = new Array(degree).fill(0);
+  result[degree - 1] = 1;
+  let root = 1;
+  for (let i = 0; i < degree; i += 1) {
+    for (let j = 0; j < result.length; j += 1) {
+      result[j] = gfMul(result[j], root);
+      if (j + 1 < result.length) result[j] ^= result[j + 1];
+    }
+    root = gfMul(root, 0x02);
+  }
+  return result;
+}
+
+function rsRemainder(data, divisor) {
+  const result = new Array(divisor.length).fill(0);
+  for (const b of data) {
+    const factor = b ^ result.shift();
+    result.push(0);
+    divisor.forEach((coef, i) => { result[i] ^= gfMul(coef, factor); });
+  }
+  return result;
+}
+
+function getBit(x, i) {
+  return ((x >>> i) & 1) !== 0;
+}
+
+// Data bits for byte mode, padded to the version's data capacity.
+function dataBytes(bytes, ver) {
+  const bits = [];
+  const push = (value, len) => {
+    for (let i = len - 1; i >= 0; i -= 1) bits.push((value >>> i) & 1);
+  };
+  push(0b0100, 4);
+  push(bytes.length, ver <= 9 ? 8 : 16);
+  for (const b of bytes) push(b, 8);
+  const capacity = dataCodewords(ver) * 8;
+  push(0, Math.min(4, capacity - bits.length));
+  push(0, (8 - (bits.length % 8)) % 8);
+  for (let pad = 0xec; bits.length < capacity; pad ^= 0xec ^ 0x11) push(pad, 8);
+  const out = [];
+  for (let i = 0; i < bits.length; i += 8) {
+    let byte = 0;
+    for (let j = 0; j < 8; j += 1) byte = (byte << 1) | bits[i + j];
+    out.push(byte);
+  }
+  return out;
+}
+
+// Split into blocks, add error correction to each, and interleave.
+function withEcc(data, ver) {
+  const numBlocks = ECC_BLOCKS[ver];
+  const eccLen = ECC_PER_BLOCK[ver];
+  const raw = Math.floor(rawDataModules(ver) / 8);
+  const numShort = numBlocks - (raw % numBlocks);
+  const shortLen = Math.floor(raw / numBlocks);
+  const divisor = rsDivisor(eccLen);
+  const blocks = [];
+  for (let i = 0, k = 0; i < numBlocks; i += 1) {
+    const dat = data.slice(k, k + shortLen - eccLen + (i < numShort ? 0 : 1));
+    k += dat.length;
+    const ecc = rsRemainder(dat, divisor);
+    if (i < numShort) dat.push(0);
+    blocks.push(dat.concat(ecc));
+  }
+  const result = [];
+  for (let i = 0; i < blocks[0].length; i += 1) {
+    blocks.forEach((block, j) => {
+      if (i !== shortLen - eccLen || j >= numShort) result.push(block[i]);
+    });
+  }
+  return result;
+}
+
+function alignmentPositions(ver) {
+  if (ver === 1) return [];
+  const size = ver * 4 + 17;
+  const numAlign = Math.floor(ver / 7) + 2;
+  const step = Math.ceil((ver * 4 + 4) / (numAlign * 2 - 2)) * 2;
+  const result = [6];
+  for (let pos = size - 7; result.length < numAlign; pos -= step) result.splice(1, 0, pos);
+  return result;
+}
+
+function makeGrid(ver) {
+  const size = ver * 4 + 17;
+  const modules = Array.from({ length: size }, () => new Array(size).fill(false));
+  const isFunction = Array.from({ length: size }, () => new Array(size).fill(false));
+  const set = (x, y, dark) => {
+    modules[y][x] = dark;
+    isFunction[y][x] = true;
+  };
+  return { ver, size, modules, isFunction, set };
+}
+
+function drawFormatBits(grid, mask) {
+  const { size, set } = grid;
+  const data = (FORMAT_BITS_M << 3) | mask;
+  let rem = data;
+  for (let i = 0; i < 10; i += 1) rem = (rem << 1) ^ ((rem >>> 9) * 0x537);
+  const bits = ((data << 10) | rem) ^ 0x5412;
+  for (let i = 0; i <= 5; i += 1) set(8, i, getBit(bits, i));
+  set(8, 7, getBit(bits, 6));
+  set(8, 8, getBit(bits, 7));
+  set(7, 8, getBit(bits, 8));
+  for (let i = 9; i < 15; i += 1) set(14 - i, 8, getBit(bits, i));
+  for (let i = 0; i < 8; i += 1) set(size - 1 - i, 8, getBit(bits, i));
+  for (let i = 8; i < 15; i += 1) set(8, size - 15 + i, getBit(bits, i));
+  set(8, size - 8, true);
+}
+
+function drawVersion(grid) {
+  const { ver, size, set } = grid;
+  if (ver < 7) return;
+  let rem = ver;
+  for (let i = 0; i < 12; i += 1) rem = (rem << 1) ^ ((rem >>> 11) * 0x1f25);
+  const bits = (ver << 12) | rem;
+  for (let i = 0; i < 18; i += 1) {
+    const bit = getBit(bits, i);
+    const a = size - 11 + (i % 3);
+    const b = Math.floor(i / 3);
+    set(a, b, bit);
+    set(b, a, bit);
+  }
+}
+
+function drawFunctionPatterns(grid) {
+  const { size, set } = grid;
+  for (let i = 0; i < size; i += 1) {
+    set(6, i, i % 2 === 0);
+    set(i, 6, i % 2 === 0);
+  }
+  const finder = (x, y) => {
+    for (let dy = -4; dy <= 4; dy += 1) {
+      for (let dx = -4; dx <= 4; dx += 1) {
+        const dist = Math.max(Math.abs(dx), Math.abs(dy));
+        const xx = x + dx;
+        const yy = y + dy;
+        if (xx >= 0 && xx < size && yy >= 0 && yy < size) set(xx, yy, dist !== 2 && dist !== 4);
+      }
+    }
+  };
+  finder(3, 3);
+  finder(size - 4, 3);
+  finder(3, size - 4);
+  const pos = alignmentPositions(grid.ver);
+  const n = pos.length;
+  for (let i = 0; i < n; i += 1) {
+    for (let j = 0; j < n; j += 1) {
+      if ((i === 0 && j === 0) || (i === 0 && j === n - 1) || (i === n - 1 && j === 0)) continue;
+      for (let dy = -2; dy <= 2; dy += 1) {
+        for (let dx = -2; dx <= 2; dx += 1) set(pos[i] + dx, pos[j] + dy, Math.max(Math.abs(dx), Math.abs(dy)) !== 1);
+      }
+    }
+  }
+  drawFormatBits(grid, 0);
+  drawVersion(grid);
+}
+
+function drawCodewords(grid, data) {
+  const { size, modules, isFunction } = grid;
+  let i = 0;
+  for (let right = size - 1; right >= 1; right -= 2) {
+    if (right === 6) right = 5;
+    for (let vert = 0; vert < size; vert += 1) {
+      for (let j = 0; j < 2; j += 1) {
+        const x = right - j;
+        const upward = ((right + 1) & 2) === 0;
+        const y = upward ? size - 1 - vert : vert;
+        if (!isFunction[y][x] && i < data.length * 8) {
+          modules[y][x] = getBit(data[i >>> 3], 7 - (i & 7));
+          i += 1;
+        }
+      }
+    }
+  }
+}
+
+const MASKS = [
+  (x, y) => (x + y) % 2 === 0,
+  (x, y) => y % 2 === 0,
+  x => x % 3 === 0,
+  (x, y) => (x + y) % 3 === 0,
+  (x, y) => (Math.floor(x / 3) + Math.floor(y / 2)) % 2 === 0,
+  (x, y) => ((x * y) % 2) + ((x * y) % 3) === 0,
+  (x, y) => (((x * y) % 2) + ((x * y) % 3)) % 2 === 0,
+  (x, y) => (((x + y) % 2) + ((x * y) % 3)) % 2 === 0,
+];
+
+function applyMask(grid, mask) {
+  const { size, modules, isFunction } = grid;
+  const test = MASKS[mask];
+  for (let y = 0; y < size; y += 1) {
+    for (let x = 0; x < size; x += 1) {
+      if (!isFunction[y][x] && test(x, y)) modules[y][x] = !modules[y][x];
+    }
+  }
+}
+
+// The spec's four penalty rules: runs of 5+ in a line, 2x2 blocks, finder
+// look-alikes (1:1:3:1:1 with 4 light on a side), and dark/light balance.
+function penalty(modules) {
+  const size = modules.length;
+  let score = 0;
+  const line = get => {
+    let run = 1;
+    for (let i = 1; i < size; i += 1) {
+      if (get(i) === get(i - 1)) {
+        run += 1;
+        if (run === 5) score += 3;
+        else if (run > 5) score += 1;
+      } else {
+        run = 1;
+      }
+    }
+    for (let i = 0; i + 10 < size + 4; i += 1) {
+      const at = k => (i + k >= 0 && i + k < size ? get(i + k) : false);
+      const core = at(0) && !at(1) && at(2) && at(3) && at(4) && !at(5) && at(6);
+      if (!core) continue;
+      const lightBefore = [1, 2, 3, 4].every(k => !at(-k));
+      const lightAfter = [7, 8, 9, 10].every(k => !at(k));
+      if (lightBefore || lightAfter) score += 40;
+    }
+  };
+  for (let y = 0; y < size; y += 1) line(x => modules[y][x]);
+  for (let x = 0; x < size; x += 1) line(y => modules[y][x]);
+  for (let y = 0; y < size - 1; y += 1) {
+    for (let x = 0; x < size - 1; x += 1) {
+      const c = modules[y][x];
+      if (c === modules[y][x + 1] && c === modules[y + 1][x] && c === modules[y + 1][x + 1]) score += 3;
+    }
+  }
+  let dark = 0;
+  for (const row of modules) for (const m of row) if (m) dark += 1;
+  const total = size * size;
+  const k = Math.ceil(Math.abs(dark * 20 - total * 10) / total) - 1;
+  score += Math.max(0, k) * 10;
+  return score;
+}
+
+function encodeQr(text, { mask: forcedMask = null } = {}) {
+  const bytes = [...Buffer.from(String(text), 'utf8')];
+  let ver = 1;
+  for (; ver <= MAX_VERSION; ver += 1) {
+    const needed = 4 + (ver <= 9 ? 8 : 16) + bytes.length * 8;
+    if (needed <= dataCodewords(ver) * 8) break;
+  }
+  if (ver > MAX_VERSION) throw new Error(`text too long for a QR code here (${bytes.length} bytes, max 213)`);
+  const grid = makeGrid(ver);
+  drawFunctionPatterns(grid);
+  drawCodewords(grid, withEcc(dataBytes(bytes, ver), ver));
+  let mask = forcedMask;
+  if (mask == null) {
+    let best = Infinity;
+    for (let m = 0; m < 8; m += 1) {
+      applyMask(grid, m);
+      drawFormatBits(grid, m);
+      const p = penalty(grid.modules);
+      if (p < best) {
+        best = p;
+        mask = m;
+      }
+      applyMask(grid, m);
+    }
+  }
+  applyMask(grid, mask);
+  drawFormatBits(grid, mask);
+  return { version: ver, size: grid.size, mask, modules: grid.modules };
+}
+
+// Terminal art: two rows of squares per line with half block characters.
+// With color on (the default) each line forces black on bright white, so the
+// code scans the same on a dark or a light terminal. With color off, light
+// squares print as blocks, which reads right on a dark terminal.
+const FULL = '█';
+const UPPER = '▀';
+const LOWER = '▄';
+
+function qrLines(text, { quiet = 2, color = true } = {}) {
+  const { modules, size } = encodeQr(text);
+  const at = (x, y) => (x >= 0 && y >= 0 && x < size && y < size ? modules[y][x] : false);
+  const lines = [];
+  for (let y = -quiet; y < size + quiet; y += 2) {
+    let line = '';
+    for (let x = -quiet; x < size + quiet; x += 1) {
+      const top = color ? at(x, y) : !at(x, y);
+      const bottom = color ? at(x, y + 1) : !at(x, y + 1);
+      line += top && bottom ? FULL : top ? UPPER : bottom ? LOWER : ' ';
+    }
+    lines.push(color ? `\x1b[30;107m${line}\x1b[0m` : line);
+  }
+  return lines;
+}
+
+module.exports = { encodeQr, qrLines, rsDivisor, rsRemainder, gfMul, dataCodewords, alignmentPositions };

package/lib/rsi-record.js

@@ -320,6 +320,93 @@ function finishAttempt(root, attempt, outcome = {}, { log = () => {} } = {}) {
   }
 }
 
+// Observed history did not run under today's policy. Use the schema directly:
+// open/finish would invent current action and completion times for old work.
+const OBSERVED_APPEND_PY = `import json, sys
+from dataclasses import asdict
+from datetime import datetime
+sys.path.insert(0, sys.argv[1])
+from backend.scripts.rsi.schema import Action, Context, Node, Outcome, append_node, tree_split
+from backend.scripts.rsi.record import get_node
+data = json.loads(sys.argv[2])
+def instant(value): return datetime.fromisoformat(value.replace('Z', '+00:00'))
+if data.get('nodeId'):
+    node = get_node(data['nodeId'])
+    if (node is None or node.lane != data['lane'] or
+        node.context.ground != data['ground'] or node.action.ground != data['ground'] or
+        node.action.engine != data['engine'] or node.action.policy_id != 'p-0000' or
+        node.context.base_commit != data['baseCommit'] or node.outcome.status == 'running' or
+        instant(node.opened_at) != instant(data['openedAt']) or
+        instant(node.created_at) != instant(data['finishedAt'])):
+        raise ValueError('observed attempt identity, policy, or provenance does not match')
+    outcome = asdict(node.outcome)
+    outcome.update(data['outcome'])
+    node.outcome = Outcome(**outcome)
+    node.recorded_at = None
+else:
+    node = Node(
+        tree_id=data['tree'], lane=data['lane'],
+        context=Context(base_commit=data['baseCommit'], ground=data['ground']),
+        action=Action(policy_id='p-0000', kind='open', ground=data['ground'], engine=data['engine'], model=None, cap_s=0),
+        outcome=Outcome(**data['outcome']), split=tree_split(data['tree']),
+        created_at=data['finishedAt'], opened_at=data['openedAt'])
+append_node(node)
+print(node.id)
+`;
+
+function observedTime(value) {
+  if (typeof value !== 'string') return NaN;
+  const match = value.match(/^(\d{4})-(\d{2})-(\d{2})T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})$/);
+  if (!match) return NaN;
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  const leap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+  const days = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+  if (month < 1 || month > 12 || day < 1 || day > days[month - 1]) return NaN;
+  return Date.parse(value);
+}
+
+/** Append measured completed work, preserving its historical provenance.
+ * Missing metadata or an unavailable backend schema defers recording. This
+ * never chooses a policy and never changes the active-attempt environment.
+ */
+function recordObservedAttempt(root, options = {}, { log = () => {} } = {}) {
+  const report = (message) => { try { log(message); } catch {} };
+  try {
+    const { lane = 'campaign', ground, engine, baseCommit, openedAt, finishedAt, outcome, nodeId } = options;
+    const engines = new Set(['codex', 'devin', 'cursor', 'agy', 'claude']);
+    const opened = observedTime(openedAt);
+    const finished = observedTime(finishedAt);
+    if (!root || !recorderPath(root) || typeof lane !== 'string' || !lane.trim() ||
+        typeof ground !== 'string' || !ground.trim() || !engines.has(engine) ||
+        typeof baseCommit !== 'string' || !/^[a-fA-F0-9]{7,64}$/.test(baseCommit) ||
+        !Number.isFinite(opened) || !Number.isFinite(finished) || opened > finished || finished > Date.now() ||
+        !outcome || typeof outcome !== 'object' || Array.isArray(outcome) ||
+        !['shipped', 'failed', 'nothing', 'waiting'].includes(outcome.status) ||
+        !['pass', 'fail', 'skipped'].includes(outcome.verify) ||
+        !Array.isArray(outcome.files) || !outcome.files.length ||
+        !Array.from(outcome.files).every((file) => typeof file === 'string' && file.trim()) ||
+        (nodeId !== undefined && (typeof nodeId !== 'string' || !nodeId.trim()))) return null;
+    const tree = nodeId ? null : startTree(root, lane);
+    if (!nodeId && !tree) {
+      report('rsi: observed attempt skipped (could not select a tree)');
+      return null;
+    }
+    const result = spawnSync(pythonBin(root), ['-c', OBSERVED_APPEND_PY, root,
+      JSON.stringify({ lane, ground, engine, baseCommit, openedAt, finishedAt, outcome, nodeId, tree })], {
+      cwd: root, encoding: 'utf8', timeout: SPAWN_TIMEOUT_MS, env: process.env,
+    });
+    const id = result.status === 0 ? String(result.stdout || '').trim().split('\n').pop() : '';
+    if (id) return id;
+    report(`rsi: observed attempt skipped${result.stderr ? ` (${String(result.stderr).trim().split('\n').pop()})` : ''}`);
+    return null;
+  } catch (error) {
+    report(`rsi: observed attempt skipped (${error && error.message ? error.message : error})`);
+    return null;
+  }
+}
+
 module.exports = {
   IMPROVE_LANE,
   GUARD_ENV,
@@ -332,4 +419,5 @@ module.exports = {
   engineFromModel,
   beginAttempt,
   finishAttempt,
+  recordObservedAttempt,
 };