@optitransfer/proofline 0.2.0-next.0 → 0.2.0-next.1

package/src/guided.mjs

@@ -0,0 +1,240 @@
+// Guided flow: setup, task, contract approve, watch. Each refusal names the next command.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import * as C from './contract.mjs';
+import * as E from './engine.mjs';
+import { connectClaudeCode } from './hook-stop.mjs';
+import { init, installHooks, approvalsDir, activeTask } from './index.mjs';
+import { git, sha256 } from './util.mjs';
+
+const TASK_SCOPE = 'src/**,bin/**,test/**,docs/**,README.md,CHANGELOG.md,package.json';
+// A few seconds: one failing sample is visible, then the loop ends if the gate is still not PASS.
+const WATCH_BOUND_MS = 6000;
+const WATCH_INTERVAL_MS = 1000;
+
+const refuse = (why, next) => new Error(`${why}\nNext step: ${next}`);
+
+function pause(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/** agentkey on PATH. AGENTKEY_HOME is required so the default key directory is never opened. */
+function agentkeyBin(env) {
+  for (const dir of String(env.PATH || '').split(path.delimiter)) {
+    if (!dir) continue;
+    const f = path.join(dir, 'agentkey');
+    try {
+      const st = fs.statSync(f);
+      if (st.isFile() && (st.mode & 0o111)) return f;
+    } catch { /* keep looking */ }
+  }
+  return null;
+}
+
+function hooksReady(root) {
+  const hd = git(['rev-parse', '--git-path', 'hooks'], root);
+  if (!hd.ok) return false;
+  const dir = path.resolve(root, hd.out);
+  for (const name of ['pre-commit', 'pre-push']) {
+    try {
+      const f = path.join(dir, name);
+      const st = fs.statSync(f);
+      if (!st.isFile() || (st.mode & 0o111) === 0) return false;
+      if (!fs.readFileSync(f, 'utf8').includes('# installed by proofline')) return false;
+    } catch { return false; }
+  }
+  return true;
+}
+
+function createOwnerKey(env) {
+  const home = env.AGENTKEY_HOME;
+  if (typeof home !== 'string' || !home.trim()) throw refuse('AGENTKEY_HOME is not set, so no key directory was opened', 'proofline setup');
+  const bin = agentkeyBin(env);
+  if (!bin) throw refuse('agentkey is not on PATH', 'proofline setup');
+  const r = spawnSync(bin, ['init', 'owner'], { encoding: 'utf8', env: { ...env, AGENTKEY_HOME: home } });
+  if (r.error || r.status !== 0) throw refuse('agentkey init owner failed', 'proofline setup');
+  const key = path.join(home, 'keys', 'owner.key');
+  let st = null;
+  try { st = fs.lstatSync(key); } catch { st = null; }
+  if (!st || !st.isFile() || st.isSymbolicLink()) throw refuse('the owner key was not created', 'proofline setup');
+}
+
+function ownerPaths(root, env) {
+  return { pub: path.join(env.AGENTKEY_HOME, 'keys', 'owner.pub'), pin: path.resolve(root, 'guard', 'owner.pub') };
+}
+
+/** The pinned bytes, or null when there is no pin. A pin that is not a regular file is refused. */
+function readPin(pin) {
+  let st;
+  try { st = fs.lstatSync(pin); } catch (e) {
+    if (e.code === 'ENOENT') return null;
+    throw refuse(`${pin} cannot be read`, `ls -l ${pin}`);
+  }
+  if (!st.isFile()) throw refuse(`${pin} is not a regular file`, `ls -l ${pin}`);
+  return fs.readFileSync(pin);
+}
+
+const pinMismatch = (pin, pub) => refuse(`${pin} does not hold the owner key at ${pub}, and a pinned owner key is never replaced`, 'AGENTKEY_HOME=<the directory that holds the pinned key> proofline setup');
+
+/** Before anything is written: a pin that is there must hold the key AGENTKEY_HOME already has. */
+function checkOwnerPin(root, env) {
+  const { pub, pin } = ownerPaths(root, env);
+  const have = readPin(pin);
+  if (!have) return;
+  let want = null;
+  try { want = fs.readFileSync(pub); } catch { want = null; }
+  if (!want || !have.equals(want)) throw pinMismatch(pin, pub);
+}
+
+/** guard/owner.pub is the only key verifyContractSignature reads. Written once from the key setup created. */
+function pinOwnerKey(root, env) {
+  const { pub, pin } = ownerPaths(root, env);
+  let want;
+  try { want = fs.readFileSync(pub); } catch { throw refuse(`the owner public key ${pub} was not created`, 'proofline setup'); }
+  const have = readPin(pin);
+  if (have) {
+    if (!have.equals(want)) throw pinMismatch(pin, pub);
+    return;
+  }
+  fs.mkdirSync(path.dirname(pin), { recursive: true });
+  fs.writeFileSync(pin, want, { flag: 'wx', mode: 0o644 });
+}
+
+/**
+ * init, hooks, the owner key, guard/owner.pub from that key, approvals at .proofline/approvals.
+ * Prints three lines. Refuses, without those lines, when a hook is missing.
+ * Refuses before init when guard/owner.pub holds a key other than the one in AGENTKEY_HOME.
+ */
+export function setup(root, { agent = 'none', env = process.env } = {}) {
+  if (agent !== 'none' && agent !== 'claude-code') throw refuse(`unknown agent ${agent}`, 'proofline setup --agent none');
+  if (!git(['rev-parse', '--show-toplevel'], root).ok) throw refuse('not a git repository', 'git init');
+  const approvals = path.resolve(root, '.proofline', 'approvals');
+  if (typeof env.AGENTKEY_HOME !== 'string' || !env.AGENTKEY_HOME.trim()) throw refuse('AGENTKEY_HOME is not set, so no key directory was opened', 'proofline setup');
+  if (!agentkeyBin(env)) throw refuse('agentkey is not on PATH', 'proofline setup');
+  checkOwnerPin(root, env);
+  try {
+    init(root, { hooks: true, approvals });
+    installHooks(root);
+  } catch {
+    throw refuse('a hook is missing', 'proofline setup');
+  }
+  if (!hooksReady(root)) throw refuse('a hook is missing', 'proofline setup');
+  createOwnerKey(env);
+  pinOwnerKey(root, env);
+  fs.mkdirSync(approvals, { recursive: true });
+  if (agent === 'claude-code') {
+    const connected = connectClaudeCode();
+    if (!connected.ok) throw refuse(connected.reason, 'proofline setup --agent claude-code');
+  }
+  return `${approvals}\nhooks installed\nproofline task\n`;
+}
+
+function freshId(text) {
+  const have = new Set((JSON.parse(text).tasks || []).map((t) => t.id));
+  let id = 'TASK';
+  let n = 2;
+  while (have.has(id)) id = `TASK-${n++}`;
+  return id;
+}
+
+/** Scaffold a task from plain words and write the proposal bytes. The contract file stays as it is. */
+export function task(root, words) {
+  const title = String(words || '').trim();
+  if (!title) throw refuse('name the task in plain words', 'proofline task "<plain words>"');
+  const file = C.contractPath(root);
+  if (!fs.existsSync(file)) throw refuse('no contract yet', 'proofline setup');
+  const before = fs.readFileSync(file, 'utf8');
+  let proposal;
+  try {
+    const spec = C.scaffoldTask({ title, scope: TASK_SCOPE, kind: 'feature', id: freshId(before) });
+    proposal = C.appendTaskText(before, [spec]);
+  } catch (e) {
+    throw refuse(e.message, 'proofline task "<plain words>"');
+  }
+  const problems = C.validate(JSON.parse(proposal));
+  if (problems.length) throw refuse(`proposal is not valid: ${problems.join('; ')}`, 'proofline task "<plain words>"');
+  const hex = sha256(proposal);
+  const dir = path.join(root, '.proofline', 'proposals');
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, hex), proposal);
+  return `${hex}\nproofline contract approve ${hex}\n`;
+}
+
+function unified(current, next) {
+  const a = path.join(os.tmpdir(), `pl-now-${process.pid}`);
+  const b = path.join(os.tmpdir(), `pl-new-${process.pid}`);
+  fs.writeFileSync(a, current);
+  fs.writeFileSync(b, next);
+  const r = spawnSync('diff', ['-u', a, b], { encoding: 'utf8' });
+  fs.rmSync(a, { force: true });
+  fs.rmSync(b, { force: true });
+  return r.stdout || '';
+}
+
+function readAnswer() {
+  process.stderr.write('Apply? [y/N] ');
+  if (process.stdin.isTTY) {
+    const buf = Buffer.alloc(256);
+    let n = 0;
+    try { n = fs.readSync(0, buf, 0, buf.length, null); } catch { n = 0; }
+    return buf.toString('utf8', 0, n).split(/\r?\n/, 1)[0].trim();
+  }
+  let raw = '';
+  try { raw = fs.readFileSync(0, 'utf8'); } catch { raw = ''; }
+  return (raw.split(/\r?\n/, 1)[0] ?? '').trim();
+}
+
+function proposalBytes(root, hash) {
+  const dir = path.join(root, '.proofline', 'proposals');
+  if (!hash) {
+    let names = [];
+    try { names = fs.readdirSync(dir).filter((n) => /^[0-9a-f]{64}$/.test(n)); } catch { names = []; }
+    if (names.length !== 1) throw refuse('name the proposal hash', 'proofline task "<plain words>"');
+    hash = names[0];
+  }
+  if (!/^[0-9a-f]{64}$/.test(hash)) throw refuse('name the proposal hash', 'proofline contract approve');
+  const file = path.join(dir, hash);
+  let bytes;
+  try { bytes = fs.readFileSync(file); } catch { throw refuse(`no proposal ${hash}`, 'proofline task "<plain words>"'); }
+  if (sha256(bytes) !== hash) throw refuse(`proposal bytes do not match ${hash}`, 'proofline task "<plain words>"');
+  return { hash, bytes };
+}
+
+/** Show the diff, then apply only on y. The marker is a regular file named by the proposal sha256. */
+export function approve(root, hash) {
+  if (!fs.existsSync(C.contractPath(root))) throw refuse('no contract yet', 'proofline setup');
+  const { hash: hex, bytes } = proposalBytes(root, hash);
+  const current = fs.readFileSync(C.contractPath(root));
+  const diff = unified(current, bytes);
+  const answer = readAnswer();
+  if (answer !== 'y' && answer !== 'Y') return `${diff}${diff.endsWith('\n') || diff === '' ? '' : '\n'}nothing applied\n`;
+  const dir = approvalsDir(root);
+  if (!dir) throw refuse('no approvals directory configured', 'proofline setup');
+  fs.mkdirSync(dir, { recursive: true });
+  const marker = path.join(dir, hex);
+  let st = null;
+  try { st = fs.lstatSync(marker); } catch { st = null; }
+  if (st && (!st.isFile() || st.isSymbolicLink())) throw refuse(`marker ${marker} is not a regular file`, `proofline contract approve ${hex}`);
+  if (!st) fs.writeFileSync(marker, '', { flag: 'wx', mode: 0o644 });
+  fs.writeFileSync(C.contractPath(root), bytes);
+  return `${diff}${diff.endsWith('\n') || diff === '' ? '' : '\n'}applied ${hex}\n`;
+}
+
+/** Print the task's criteria until the gate is PASS, or return non-zero when the bound ends. */
+export function watch(root, taskArg) {
+  const id = taskArg || activeTask(root);
+  if (!id) throw refuse('no active task', 'proofline next');
+  const start = Date.now();
+  for (;;) {
+    let g;
+    try { g = E.gate(root, id); }
+    catch (e) { throw refuse(e.message, 'proofline next'); }
+    const lines = (g.results || []).map((r) => `  ${String(r.status).toUpperCase()} ${r.id} ${r.statement || ''}`.trimEnd());
+    process.stdout.write(`${g.task} ${g.decision}\n${lines.join('\n')}\n`);
+    if (g.decision === 'PASS') return 0;
+    if (Date.now() - start >= WATCH_BOUND_MS) return 1;
+    pause(Math.min(WATCH_INTERVAL_MS, WATCH_BOUND_MS - (Date.now() - start)));
+  }
+}

package/src/hook-stop.mjs

@@ -0,0 +1,105 @@
+// Claude Code Stop hook: one receipt for the commits a session made, and none on the next run.
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { buildReceipt } from './receipt.mjs';
+
+export const STOP_COMMAND = 'proofline hook stop';
+
+function git(root, args) {
+  return execFileSync('git', args, { cwd: root, encoding: 'utf8' }).trim();
+}
+
+function sessionStart(transcriptPath) {
+  if (!transcriptPath || !fs.existsSync(transcriptPath)) return null;
+  for (const line of fs.readFileSync(transcriptPath, 'utf8').split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const row = JSON.parse(line);
+      const ts = row.timestamp || row.ts;
+      if (typeof ts === 'string' && ts) return ts;
+    } catch { /* a later line may carry the time */ }
+  }
+  return null;
+}
+
+function markerFile(root) {
+  return path.join(root, '.proofline', 'session');
+}
+
+function readMarker(root) {
+  try { return JSON.parse(fs.readFileSync(markerFile(root), 'utf8')); }
+  catch { return null; }
+}
+
+function commitsSince(root, since) {
+  const out = git(root, ['rev-list', `${since}..HEAD`]);
+  return out ? out.split('\n').filter(Boolean) : [];
+}
+
+function commitsForSession(root, start, sessionId) {
+  const found = new Set();
+  const startMs = start ? Date.parse(start) : NaN;
+  if (!Number.isNaN(startMs)) {
+    const out = git(root, ['log', '--format=%H%x09%cI']);
+    for (const line of out.split('\n')) {
+      const [sha, when] = line.split('\t');
+      if (sha && Date.parse(when) >= startMs) found.add(sha);
+    }
+  }
+  if (sessionId) {
+    try {
+      const out = git(root, ['log', '-F', '--format=%H', `--grep=Agent-Run: ${sessionId}`]);
+      for (const sha of out.split('\n')) if (sha) found.add(sha);
+    } catch { /* a git that rejects the flag still keeps the commits matched by time */ }
+  }
+  return [...found];
+}
+
+export async function hookStop(root, payload = {}) {
+  let head = '';
+  try { head = git(root, ['rev-parse', 'HEAD']); }
+  catch { return { receipts: [] }; }
+  const marker = readMarker(root);
+  if (marker?.receipted === head) return { receipts: [] };
+  let commits = [];
+  try {
+    commits = marker?.receipted
+      ? commitsSince(root, marker.receipted)
+      : commitsForSession(root, sessionStart(payload.transcript_path), payload.session_id || '');
+  } catch { return { receipts: [] }; }
+  if (!commits.length) return { receipts: [] };
+  let base = marker?.receipted;
+  if (!base) {
+    try { base = git(root, ['rev-parse', `${commits[commits.length - 1]}^`]); }
+    catch { base = undefined; }
+  }
+  const receipt = await buildReceipt(root, { base, role: 'claude-code' });
+  fs.mkdirSync(path.dirname(markerFile(root)), { recursive: true });
+  fs.writeFileSync(markerFile(root), JSON.stringify({ session_id: payload.session_id || '', receipted: head }) + '\n');
+  return { receipts: [{ ...receipt, role: 'claude-code' }] };
+}
+
+export function connectClaudeCode(home = os.homedir()) {
+  const file = path.join(home, '.claude', 'settings.json');
+  let settings = {};
+  if (fs.existsSync(file)) {
+    let parsed;
+    try { parsed = JSON.parse(fs.readFileSync(file, 'utf8')); }
+    catch { return { ok: false, file, reason: 'settings.json is not plain JSON, so nothing was changed' }; }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return { ok: false, file, reason: 'settings.json is not an object, so nothing was changed' };
+    }
+    settings = parsed;
+  }
+  const hooks = settings.hooks && typeof settings.hooks === 'object' && !Array.isArray(settings.hooks) ? settings.hooks : {};
+  const stop = Array.isArray(hooks.Stop) ? hooks.Stop.slice() : [];
+  if (!stop.some((entry) => JSON.stringify(entry).includes(STOP_COMMAND))) {
+    stop.push({ hooks: [{ type: 'command', command: STOP_COMMAND }] });
+  }
+  settings.hooks = { ...hooks, Stop: stop };
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
+  return { ok: true, file };
+}

package/src/index.mjs

@@ -1,5 +1,6 @@
 // Public API used by the CLI and the MCP server.
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import * as C from './contract.mjs';
 import * as E from './engine.mjs';
@@ -97,21 +98,147 @@ export function contractCreate(root, spec) {
   return { task: t, valid: errs.length === 0, problems: errs };
 }
 
-export function taskNext(root, { owner } = {}) {
-  const n = E.next(root, { owner });
-  if (n.task && n.status === 'not_started') { const c = C.load(root);
-    const base = resolveBase(root, C.defaultBase(c)) || git(['rev-parse', 'HEAD'], root).out;
-    record(root, 'task_started', { task: n.task, base, ...(owner ? { owner } : {}) }); n.status = 'in_progress'; }
+export function taskNext(root, { owner, base: explicitBase } = {}) {
+  const settled = settleLanded(root);
+  let c;
+  try { c = C.load(root); } catch { c = { tasks: [] }; }
+  const n = E.next(root, { owner, skip: c.tasks.map((t) => t.id).filter((id) => landedWhy(root, id)) });
+  if (n.task && (n.status === 'not_started' || explicitBase)) {
+    const loaded = C.load(root);
+    let base;
+    if (explicitBase) {
+      base = resolveBase(root, explicitBase);
+      if (!base) throw new Error(`base revision "${explicitBase}" not found`);
+    } else base = resolveBase(root, C.defaultBase(loaded)) || git(['rev-parse', 'HEAD'], root).out;
+    record(root, 'task_started', { task: n.task, base, ...(owner ? { owner } : {}) }); n.status = 'in_progress';
+  }
   if (n.task) {
     fs.writeFileSync(path.join(root, '.proofline', 'active'), n.task + '\n');
-    n.base = readLog(root).find((e) => e.type === 'task_started' && e.data.task === n.task)?.data.base;
+    n.base = E.latestStart(root, n.task);
     if (n.base) n.brief += `\n\n## Base\nPinned at start: ${n.base}. The pin lives in the local .proofline/ log; in another clone, gate with \`--base ${n.base}\`, or end the task commit message with the trailer \`Proofline-Base: ${n.base}\`.`;
   }
+  if (settled) {
+    n.landed = settled.message;
+    if (n.brief) n.brief = `${settled.message}\n\n${n.brief}`;
+    else n.message = n.message ? `${settled.message}\n\n${n.message}` : settled.message;
+  }
   return n;
 }
 
 export const activeTask = (root) => { try { return fs.readFileSync(path.join(root, '.proofline', 'active'), 'utf8').trim() || null; } catch { return null; } };
 
+const activePath = (root) => path.join(root, '.proofline', 'active');
+
+/** Task id named by a commit message: a (TASK-ID) subject suffix, else a Proofline-Task trailer. */
+export function taskFromMessage(body, known) {
+  const subject = String(body || '').split('\n')[0];
+  const m = subject.match(/\(([A-Za-z][A-Za-z0-9-]*)\)\s*$/);
+  if (m && known.has(m[1])) return m[1];
+  const last = String(body || '').trim().split(/\n[ \t]*\n/).pop() || '';
+  for (const line of last.split('\n')) {
+    const t = line.match(/^Proofline-Task:[ \t]*(\S+)\s*$/);
+    if (t && known.has(t[1])) return t[1];
+  }
+  return null;
+}
+
+/** Newest commit on origin/main that names `id`, or null. */
+function namedHeadOnMain(root, id) {
+  const log = git(['log', 'origin/main', '-z', '--format=%H%x1f%B'], root);
+  if (!log.ok || !log.out) return null;
+  const known = new Set([id]);
+  for (const rec of log.out.split('\0')) {
+    const i = rec.indexOf('\x1f');
+    if (i < 0) continue;
+    const sha = rec.slice(0, i).trim();
+    if (taskFromMessage(rec.slice(i + 1), known)) return sha;
+  }
+  return null;
+}
+
+/**
+ * A pushed criterion PASS in the latest report.
+ * A PASS recorded at an older HEAD is stale once the task has new commits, so it does not count as landed.
+ * A report with no head (a recorded PASS and nothing else) still counts.
+ */
+function pushedPass(root, id) {
+  let head = null;
+  let pass = false;
+  try {
+    const j = JSON.parse(fs.readFileSync(path.join(root, '.proofline', 'reports', `${id}-latest.json`), 'utf8'));
+    pass = (j.results || []).some((r) => r.type === 'pushed' && r.status === 'pass');
+    if (typeof j.head === 'string' && /^[0-9a-f]{40}$/.test(j.head)) head = j.head;
+  } catch { return false; }
+  if (!pass) return false;
+  if (!head) {
+    const log = readLog(root);
+    for (let i = log.length - 1; i >= 0; i--) {
+      const e = log[i];
+      if (e.type === 'gate' && e.data?.task === id && /^[0-9a-f]{40}$/.test(e.data.head || '')) { head = e.data.head; break; }
+    }
+  }
+  if (!head) return true;
+  return git(['rev-parse', 'HEAD'], root).out === head;
+}
+
+/** Why an active task has landed, or null. Does not touch the active file. */
+export function landedWhy(root, id) {
+  let c;
+  try { c = C.load(root); } catch { return null; }
+  if (!c.tasks?.some((t) => t.id === id)) return null;
+  const sha = namedHeadOnMain(root, id);
+  if (sha) return { kind: 'head', sha };
+  if (pushedPass(root, id)) return { kind: 'pushed' };
+  return null;
+}
+
+function landedMessage(id, why) {
+  if (why.kind === 'head') return `${id} landed: its head ${why.sha.slice(0, 8)} is an ancestor of origin/main. Cleared .proofline/active.`;
+  return `${id} landed: its pushed criterion has a PASS record. Cleared .proofline/active.`;
+}
+
+/** Clear .proofline/active when that task has landed. Returns the sentence to report, or null. */
+export function settleLanded(root) {
+  const id = activeTask(root);
+  if (!id) return null;
+  const why = landedWhy(root, id);
+  if (!why) return null;
+  fs.rmSync(activePath(root), { force: true });
+  return { task: id, message: landedMessage(id, why) };
+}
+
+/** Server default-branch head for this push URL, from `git ls-remote` now. Never reads refs/remotes. */
+function serverDefaultHead(root, pushUrl) {
+  if (typeof pushUrl !== 'string' || !pushUrl.trim()) return { ok: false };
+  const ls = git(['ls-remote', pushUrl, 'HEAD'], root);
+  if (!ls.ok) return { ok: false };
+  const sha = (ls.out.split(/\s+/)[0] || '');
+  if (!sha) return { ok: true, sha: '' };
+  if (!/^[0-9a-f]{40}$/i.test(sha)) return { ok: false };
+  return { ok: true, sha };
+}
+
+function commitsOnPushLine(root, line, pushUrl) {
+  const p = line.trim().split(/\s+/);
+  if (p.length < 4) return [];
+  const local = p[1];
+  const remote = p[3];
+  if (!/^[0-9a-f]{40}$/i.test(local) || /^0+$/.test(local)) return [];
+  // Existing branch: remote..local. New branch: every commit reachable from local.
+  // Already sent means reachable from the server default-branch head. A local
+  // remote-tracking ref is not that head. An unreadable server gates the whole range.
+  const range = /^0+$/.test(remote) ? [local] : [`${remote}..${local}`];
+  const listed = git(['rev-list', ...range], root);
+  if (!listed.ok) return [];
+  const all = listed.out ? listed.out.split('\n').filter(Boolean) : [];
+  const server = serverDefaultHead(root, pushUrl);
+  if (!server.ok || !server.sha) return all;
+  if (!git(['cat-file', '-e', `${server.sha}^{commit}`], root).ok) return all;
+  const filtered = git(['rev-list', ...range, '--not', server.sha], root);
+  if (!filtered.ok) return all;
+  return filtered.out ? filtered.out.split('\n').filter(Boolean) : [];
+}
+
 export function evidenceRecord(root, type, data, actor = 'agent') {
   // Agent-recorded evidence is stored as a claim-class event; it is never used to pass a gate.
   return record(root, `agent_${type}`, data, { actor });
@@ -159,6 +286,8 @@ export function approvalsDir(root) {
  *  A weakening passes only when an approval marker named with the sha256 of those bytes exists.
  *  What else is staged does not matter. There is no bypass. */
 export function hookPreCommit(root) {
+  // Do not clear here. The commit under way is not HEAD yet, so a PASS recorded at the
+  // current head would look landed and the active task would be dropped before its own commit.
   const c = C.load(root);
   const head = git(['rev-parse', '--verify', '--quiet', 'HEAD'], root);
   if (!head.ok) return { ok: true, msg: 'first commit' };
@@ -170,11 +299,16 @@ export function hookPreCommit(root) {
     let cur; try { cur = JSON.parse(staged.toString('utf8')); } catch { return { ok: false, msg: 'staged proofline.json is not valid JSON' }; }
     let base = null; const s = git(['show', 'HEAD:proofline.json'], root); if (s.ok) try { base = JSON.parse(s.out); } catch {}
     w = C.weakenings(base, cur);
-    if (w.length) {
+    const fields = base && cur ? C.contractFieldChanges(base, cur) : [];
+    if (w.length || fields.length) {
       // Same check as verify and gate: a regular file named with the sha256 of these bytes.
       const mark = approvalMarker(root, staged);
       if (mark.approved) w = [];
-      else note = [`sha256 ${mark.hex}`, mark.marker ? `marker ${mark.marker}` : 'marker (no approvals directory configured)'].join('\n');
+      else {
+        note = [`sha256 ${mark.hex}`, mark.marker ? `marker ${mark.marker}` : 'marker (no approvals directory configured)'].join('\n');
+        // One explanation line. A non-weakening edit is still the hash refusal.
+        w = [w.length ? w.join('; ') : 'canonical bytes differ from HEAD'];
+      }
     }
   } else if (git(['cat-file', '-e', 'HEAD:proofline.json'], root).ok) {
     // Removed from the index. There are no staged bytes, so no marker name can approve the removal.
@@ -182,22 +316,116 @@ export function hookPreCommit(root) {
     w = C.weakenings(base, { tasks: [] });
     note = 'staged proofline.json is absent, so no approval marker can be bound to its bytes';
   }
-  const msgs = [...f.map((x) => `forbidden ${x.rule}: ${x.file}: ${x.line} (${x.why})`), ...w.map((x) => `contract weakened: ${x}`), ...(note ? [note] : [])];
-  return { ok: msgs.length === 0, msg: msgs.join('\n') };
+  const problems = [...f.map((x) => `forbidden ${x.rule}: ${x.file}: ${x.line} (${x.why})`), ...w.map((x) => `contract weakened: ${x}`), ...(note ? [note] : [])];
+  return { ok: problems.length === 0, msg: problems.join('\n') };
+}
+
+const GIT_ENV = ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_PREFIX', 'GIT_COMMON_DIR', 'GIT_OBJECT_DIRECTORY', 'GIT_NAMESPACE', 'GIT_QUARANTINE_PATH'];
+
+/** A pre-push hook exports GIT_DIR. Drop it so the gate sees the temporary worktree, then put it back. */
+function withoutGitEnv(fn) {
+  const saved = {};
+  for (const k of GIT_ENV) {
+    if (Object.prototype.hasOwnProperty.call(process.env, k)) { saved[k] = process.env[k]; delete process.env[k]; }
+  }
+  try { return fn(); }
+  finally {
+    for (const k of GIT_ENV) {
+      if (Object.prototype.hasOwnProperty.call(saved, k)) process.env[k] = saved[k];
+      else delete process.env[k];
+    }
+  }
 }
 
-/** pre-push: the active task (or every in-progress task) must gate PASS on this exact HEAD. */
-export function hookPrePush(root) {
+/**
+ * Gate `id` at `sha` in a temporary worktree. The base is the most recent start pin in `root`,
+ * otherwise the parent of `sha`. The refusal names that base. Stale evidence in `root` is not copied.
+ */
+function gateAtCommit(root, sha, id) {
+  const pinned = E.latestStart(root, id);
+  const parent = git(['rev-parse', '--verify', '--quiet', `${sha}^`], root);
+  const baseRef = pinned || (parent.ok ? parent.out : null);
+  const named = baseRef || 'none';
+  if (!baseRef) return { ok: false, msg: `${id} at ${sha}: no base\nbase ${named}` };
+  return withoutGitEnv(() => {
+    const wt = fs.mkdtempSync(path.join(os.tmpdir(), 'proofline-push-'));
+    let added = false;
+    try {
+      const add = git(['worktree', 'add', '--detach', '--force', wt, sha], root);
+      if (!add.ok) return { ok: false, msg: `${id} at ${sha}: worktree failed: ${add.err}\nbase ${baseRef}` };
+      added = true;
+      let g;
+      try { g = E.gate(wt, id, { skipTypes: ['pushed'], base: baseRef }); }
+      catch (e) { return { ok: false, msg: `${id} at ${sha}: ${e.message}\nbase ${baseRef}` }; }
+      const used = g.base || baseRef;
+      if (g.decision !== 'PASS') return { ok: false, msg: `${id} at ${sha}: ${g.decision}\nbase ${used}\n${g.corrective_prompt}` };
+      return { ok: true, msg: `gated ${id} at ${sha}\nbase ${used}` };
+    } finally {
+      if (added) git(['worktree', 'remove', '--force', wt], root);
+      fs.rmSync(wt, { recursive: true, force: true });
+    }
+  });
+}
+
+/**
+ * pre-push. A push is gated on the commit being pushed: the local sha from stdin, at that sha,
+ * not the checked-out HEAD. The task is the (TASK-ID) subject suffix or a Proofline-Task trailer.
+ * A commit that names none falls back to the active task. No active task and no named task is a refusal
+ * that prints `proofline next`. An active task that has landed is cleared and never gated.
+ * With no push lines (a direct call), the previous rule stands: the active task, else every in-progress or failed task.
+ */
+export function hookPrePush(root, { lines, pushUrl } = {}) {
+  // stdin lines are `<local ref> <local sha> <remote ref> <remote sha>`. The gated revision is that sha.
+  if (lines == null) {
+    let raw = '';
+    try { if (!process.stdin.isTTY) raw = fs.readFileSync(0, 'utf8'); } catch { raw = ''; }
+    lines = raw.split('\n').filter((l) => l.trim());
+  }
+  const settled = settleLanded(root);
   const c = C.load(root);
   const errs = C.validate(c);
-  if (errs.length) return { ok: false, msg: 'contract invalid:\n' + errs.join('\n') };
+  const note = settled?.message || '';
+  const join = (...parts) => parts.flat().filter(Boolean).join('\n\n');
+  if (errs.length) return { ok: false, msg: join(note, 'contract invalid:\n' + errs.join('\n')) };
+  const haveLines = Array.isArray(lines) && lines.some((l) => l.trim());
+  if (haveLines) {
+    const known = new Set(c.tasks.map((t) => t.id));
+    const commits = [...new Set(lines.flatMap((l) => commitsOnPushLine(root, l, pushUrl)))];
+    if (commits.length) {
+      const active = activeTask(root);
+      const activeLive = active && !landedWhy(root, active) ? active : null;
+      const jobs = [];
+      for (const sha of commits) {
+        const body = git(['log', '-1', '--format=%B', sha], root).out || '';
+        const id = taskFromMessage(body, known);
+        if (id) jobs.push({ sha, id });
+        else if (activeLive) jobs.push({ sha, id: activeLive });
+      }
+      if (!jobs.length) {
+        const started = readLog(root).some((e) => e.type === 'task_started');
+        if (!started) return { ok: true, msg: join(note, 'No task has a start record. Next step: proofline next') };
+        return { ok: false, msg: join(note, 'no active task and no commit names a task.\nNext step: proofline next') };
+      }
+      const bad = [];
+      const good = [];
+      for (const job of jobs) {
+        if (!c.tasks.some((t) => t.id === job.id)) continue;
+        const g = gateAtCommit(root, job.sha, job.id);
+        if (!g.ok) bad.push(g.msg);
+        else if (g.msg) good.push(g.msg);
+      }
+      return { ok: bad.length === 0, msg: join(note, bad.length ? bad.join('\n\n') : good.join('\n\n')) };
+    }
+  }
   const st = E.taskStatus(root, c);
-  const ids = activeTask(root) ? [activeTask(root)] : Object.keys(st).filter((k) => st[k].status === 'in_progress' || st[k].status === 'failed');
+  const active = activeTask(root);
+  let ids = active ? [active] : Object.keys(st).filter((k) => st[k].status === 'in_progress' || st[k].status === 'failed');
+  ids = ids.filter((id) => !landedWhy(root, id));
   const out = [];
   for (const id of ids) {
     if (!c.tasks.some((t) => t.id === id)) continue;
     const g = E.gate(root, id, { skipTypes: ['pushed'] });
     if (g.decision !== 'PASS') out.push(`${id}: ${g.decision}\n${g.corrective_prompt}`);
   }
-  return { ok: out.length === 0, msg: out.join('\n\n') };
+  return { ok: out.length === 0, msg: join(note, out.join('\n\n')) };
 }