instar 0.28.52 → 0.28.53

package/scripts/destructive-command-shim.js

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+/**
+ * destructive-command-shim.js — guard `git`/`rm` invocations inside topic worktrees.
+ *
+ * Per PARALLEL-DEV-ISOLATION-SPEC.md "Destructive-command interception (iter 4 — MANDATORY)".
+ *
+ * Behavior:
+ *   - For non-destructive `git`/`rm` invocations: pass through transparently.
+ *   - For destructive ones (git clean -fd, git reset --hard, rm -rf with >5 entries, etc.):
+ *       1. Compute would-affect file count (dry-run).
+ *       2. If snapshot needed: tar+zstd the worktree to .instar/worktrees/.snapshots/
+ *          with chmod 0600. BLOCK if snapshot fails.
+ *       3. Append event to .instar/worktrees/.lock-history.jsonl
+ *       4. Forward to the real binary.
+ *
+ * Real binaries are resolved by stripping the shim dir from PATH and re-resolving.
+ *
+ * Usage: destructive-command-shim.js <git|rm> <original args...>
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn, execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const SECURE_FILE_MODE = 0o600;
+const DESTRUCTIVE_FILE_THRESHOLD = 5;
+
+function findWorktreeRoot(startCwd) {
+  let cwd = startCwd;
+  for (let i = 0; i < 10; i++) {
+    if (fs.existsSync(path.join(cwd, '.session.lock'))) return cwd;
+    const parent = path.dirname(cwd);
+    if (parent === cwd) break;
+    cwd = parent;
+  }
+  return null;
+}
+
+function findStateRoot(worktreeRoot) {
+  // .instar/worktrees/<wt>/ → .instar/worktrees/.snapshots/
+  let cwd = worktreeRoot;
+  for (let i = 0; i < 5; i++) {
+    if (path.basename(cwd) === 'worktrees' && path.basename(path.dirname(cwd)) === '.instar') {
+      return path.dirname(path.dirname(cwd));
+    }
+    cwd = path.dirname(cwd);
+  }
+  return null;
+}
+
+function resolveRealBinary(name) {
+  const sessionShim = process.env.INSTAR_SHIM_DIR;
+  // Strip shim dir from PATH and re-resolve
+  let pathParts = (process.env.PATH ?? '').split(':');
+  if (sessionShim) pathParts = pathParts.filter(p => p !== sessionShim);
+  const cleanPath = pathParts.join(':');
+
+  for (const dir of pathParts) {
+    const candidate = path.join(dir, name);
+    try {
+      const st = fs.statSync(candidate);
+      if (st.isFile() && (st.mode & 0o111)) return { path: candidate, env: { ...process.env, PATH: cleanPath } };
+    } catch { /* keep looking */ }
+  }
+  // Fallback: known absolute paths
+  const known = name === 'git'
+    ? ['/usr/bin/git', '/opt/homebrew/bin/git', '/usr/local/bin/git']
+    : ['/bin/rm', '/usr/bin/rm'];
+  for (const k of known) {
+    if (fs.existsSync(k)) return { path: k, env: { ...process.env, PATH: cleanPath } };
+  }
+  throw new Error(`could not resolve real ${name}`);
+}
+
+function isDestructiveGit(args) {
+  if (args.length === 0) return false;
+  const a = args[0];
+
+  if (a === 'clean') {
+    // -f with -d (or -fd) is destructive
+    return args.some(x => /-.*[fd].*[fd]/.test(x) || x === '-fd' || x === '-fdx' || x === '-fx');
+  }
+  if (a === 'reset') {
+    return args.includes('--hard');
+  }
+  if (a === 'checkout') {
+    // git checkout -- . / git checkout HEAD -- .
+    return args.includes('--') || args.includes('.');
+  }
+  if (a === 'rm') {
+    return args.includes('-r') || args.includes('-rf') || args.includes('-fr');
+  }
+  return false;
+}
+
+function isDestructiveRm(args) {
+  return args.some(x => /^-.*r/.test(x)) && args.some(x => /^-.*f/.test(x));
+}
+
+function dryRunGitClean(cwd, args) {
+  // Use -n to count what would be removed
+  const dryArgs = ['-C', cwd, 'clean', '-n', ...args.filter(a => a !== '-f')];
+  try {
+    const out = execFileSync('git', dryArgs, { encoding: 'utf-8', timeout: 5000 });
+    return out.split('\n').filter(Boolean).length;
+  } catch { return Number.POSITIVE_INFINITY; }
+}
+
+function snapshotWorktree(worktreeRoot, stateRoot) {
+  const snapshotsDir = path.join(stateRoot, 'worktrees', '.snapshots');
+  fs.mkdirSync(snapshotsDir, { recursive: true });
+  const ts = Date.now();
+  const wtName = path.basename(worktreeRoot);
+  const candidate = path.join(snapshotsDir, `${wtName}-${ts}.tar.zst`);
+  const fallback = path.join(snapshotsDir, `${wtName}-${ts}.tar.gz`);
+
+  const exclusions = ['node_modules', 'dist', '.next', 'build', 'target', '.cache'];
+  const excludeArgs = exclusions.flatMap(x => ['--exclude', x]);
+
+  // Try zstd first
+  try {
+    execFileSync('zstd', ['--version'], { stdio: 'pipe' });
+    execFileSync('sh', ['-c',
+      `tar -C "${path.dirname(worktreeRoot)}" ${excludeArgs.map(a => `'${a}'`).join(' ')} -cf - "${path.basename(worktreeRoot)}" | zstd -o "${candidate}"`,
+    ], { stdio: 'inherit', timeout: 30_000 });
+    fs.chmodSync(candidate, SECURE_FILE_MODE);
+    return candidate;
+  } catch {
+    // Fallback: tar + gzip
+    execFileSync('tar', [
+      '-C', path.dirname(worktreeRoot),
+      ...excludeArgs,
+      '-czf', fallback,
+      path.basename(worktreeRoot),
+    ], { stdio: 'inherit', timeout: 30_000 });
+    fs.chmodSync(fallback, SECURE_FILE_MODE);
+    return fallback;
+  }
+}
+
+function appendHistoryEvent(worktreeRoot, event) {
+  const histFile = path.join(worktreeRoot, '.lock-history.jsonl');
+  const entry = JSON.stringify({ ts: Date.now(), ...event });
+  fs.appendFileSync(histFile, `${entry}\n`, { mode: SECURE_FILE_MODE });
+}
+
+function passthrough(realBin, args) {
+  const child = spawn(realBin.path, args, {
+    stdio: 'inherit',
+    env: realBin.env,
+  });
+  child.on('exit', (code) => process.exit(code ?? 0));
+  child.on('error', (err) => { console.error(err.message); process.exit(127); });
+}
+
+async function main() {
+  const cmd = process.argv[2];
+  const args = process.argv.slice(3);
+
+  if (!['git', 'rm'].includes(cmd)) {
+    console.error(`destructive-command-shim: unknown command "${cmd}"`);
+    process.exit(2);
+  }
+
+  const realBin = resolveRealBinary(cmd);
+  const cwd = process.cwd();
+  const worktreeRoot = findWorktreeRoot(cwd);
+
+  // Not inside a managed worktree → passthrough silently
+  if (!worktreeRoot) return passthrough(realBin, args);
+
+  const isDestructive = cmd === 'git' ? isDestructiveGit(args) : isDestructiveRm(args);
+  if (!isDestructive) return passthrough(realBin, args);
+
+  // Determine if this would affect >5 files
+  let affectedCount = Number.POSITIVE_INFINITY;
+  if (cmd === 'git' && args[0] === 'clean') {
+    affectedCount = dryRunGitClean(worktreeRoot, args);
+  } else if (cmd === 'rm') {
+    // rm -rf <paths>: count entries
+    const targets = args.filter(a => !a.startsWith('-'));
+    affectedCount = targets.length;
+  }
+
+  // For all other destructive cmds (reset --hard, checkout -- .): always snapshot
+  const shouldSnapshot = affectedCount > DESTRUCTIVE_FILE_THRESHOLD || cmd === 'git' && (args[0] === 'reset' || args[0] === 'checkout');
+
+  if (shouldSnapshot) {
+    const stateRoot = findStateRoot(worktreeRoot);
+    if (!stateRoot) {
+      console.error('destructive-command-shim: BLOCK — could not locate .instar state root');
+      process.exit(1);
+    }
+    let snapshotPath;
+    try {
+      snapshotPath = snapshotWorktree(worktreeRoot, stateRoot);
+    } catch (err) {
+      console.error(`destructive-command-shim: BLOCK — snapshot failed: ${err.message}`);
+      process.exit(1);
+    }
+    appendHistoryEvent(worktreeRoot, {
+      kind: 'destructive-cmd-snapshotted',
+      cmd,
+      args,
+      snapshotPath,
+      affectedCount,
+    });
+    console.error(`destructive-command-shim: snapshotted to ${snapshotPath} before "${cmd} ${args.join(' ')}"`);
+  }
+
+  return passthrough(realBin, args);
+}
+
+main().catch((err) => {
+  console.error(`destructive-command-shim: BLOCK — ${err.message}`);
+  process.exit(1);
+});

package/scripts/gh-ruleset-install.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+/**
+ * gh-ruleset-install.mjs — install the GitHub Repository Ruleset for parallel-dev.
+ *
+ * Per PARALLEL-DEV-ISOLATION-SPEC.md "Authoritative push gate (iter 4 — GH ruleset)".
+ *
+ * Creates a ruleset with:
+ *   - Targets: main, topic/*, platform/*, tags v*
+ *   - restrict_updates / restrict_creations / restrict_deletions / non_fast_forward
+ *   - required_status_checks: worktree-trailer-sig-check
+ *   - bypass_actors: [] (no admin bypass; github-actions[bot] allowed only for PR-merge commits)
+ *   - second ruleset entry: 2-approval rule on `.github/workflows/worktree-trailer-sig-check.yml`
+ *     and `.github/scripts/verify-trailers.js` paths
+ *
+ * Calls `gh api` with the user's authenticated PAT (must have `repo` scope).
+ *
+ * Usage:
+ *   gh-ruleset-install.mjs <owner> <repo> [--mode evaluate|active]
+ *
+ * Mode `evaluate` (default for first install): logs would-block, doesn't enforce.
+ * Mode `active`: enforces. Recommended after Day-7 cutover-gate is satisfied.
+ */
+
+import { execFileSync } from 'node:child_process';
+
+const [, , owner, repo, ...rest] = process.argv;
+if (!owner || !repo) {
+  console.error('Usage: gh-ruleset-install.mjs <owner> <repo> [--mode evaluate|active]');
+  process.exit(2);
+}
+const modeFlag = rest.find((a) => a.startsWith('--mode='));
+const mode = (rest.includes('--mode') ? rest[rest.indexOf('--mode') + 1] : modeFlag?.split('=')[1]) ?? 'evaluate';
+if (!['evaluate', 'active'].includes(mode)) {
+  console.error(`invalid --mode "${mode}" — must be evaluate|active`);
+  process.exit(2);
+}
+
+function ghApi(method, path, bodyObj = null) {
+  const args = ['api', '--method', method, path, '-H', 'Accept: application/vnd.github+json'];
+  if (bodyObj !== null) {
+    for (const [k, v] of Object.entries(bodyObj)) {
+      args.push('--field', `${k}=${typeof v === 'string' ? v : JSON.stringify(v)}`);
+    }
+  }
+  try {
+    return execFileSync('gh', args, { encoding: 'utf-8' });
+  } catch (err) {
+    console.error(`gh-ruleset-install: gh api failed: ${err.message}`);
+    if (err.stderr) console.error(err.stderr.toString());
+    throw err;
+  }
+}
+
+const branchRuleset = {
+  name: 'instar-parallel-dev-isolation',
+  target: 'branch',
+  enforcement: mode,
+  bypass_actors: [],
+  conditions: {
+    ref_name: {
+      include: ['~DEFAULT_BRANCH', 'refs/heads/main', 'refs/heads/topic/*', 'refs/heads/platform/*'],
+      exclude: [],
+    },
+  },
+  rules: [
+    { type: 'deletion' },
+    { type: 'non_fast_forward' },
+    {
+      type: 'required_status_checks',
+      parameters: {
+        strict_required_status_checks_policy: true,
+        required_status_checks: [
+          { context: 'worktree-trailer-sig-check / verify' },
+        ],
+      },
+    },
+    {
+      type: 'pull_request',
+      parameters: {
+        required_approving_review_count: 0,
+        dismiss_stale_reviews_on_push: false,
+        require_code_owner_review: false,
+        require_last_push_approval: false,
+        required_review_thread_resolution: false,
+      },
+    },
+  ],
+};
+
+const tagRuleset = {
+  name: 'instar-tag-protection',
+  target: 'tag',
+  enforcement: mode,
+  bypass_actors: [],
+  conditions: {
+    ref_name: { include: ['refs/tags/v*'], exclude: [] },
+  },
+  rules: [
+    { type: 'deletion' },
+    { type: 'non_fast_forward' },
+  ],
+};
+
+const trustRootRuleset = {
+  name: 'instar-trust-root-2-approval',
+  target: 'branch',
+  enforcement: 'active',  // always enforced (per K4)
+  bypass_actors: [],
+  conditions: {
+    ref_name: { include: ['~DEFAULT_BRANCH'], exclude: [] },
+  },
+  rules: [
+    {
+      type: 'pull_request',
+      parameters: {
+        required_approving_review_count: 2,
+        require_code_owner_review: false,
+        dismiss_stale_reviews_on_push: true,
+        require_last_push_approval: true,
+        required_review_thread_resolution: true,
+      },
+    },
+    {
+      type: 'file_path_restriction',
+      parameters: {
+        restricted_file_paths: [
+          '.github/workflows/worktree-trailer-sig-check.yml',
+          '.github/scripts/verify-trailers.js',
+          'scripts/gh-ruleset-install.mjs',
+        ],
+      },
+    },
+  ],
+};
+
+console.log(`gh-ruleset-install: installing ruleset on ${owner}/${repo} (mode=${mode})`);
+ghApi('POST', `/repos/${owner}/${repo}/rulesets`, branchRuleset);
+console.log('  ✓ branch ruleset installed');
+ghApi('POST', `/repos/${owner}/${repo}/rulesets`, tagRuleset);
+console.log('  ✓ tag ruleset installed');
+ghApi('POST', `/repos/${owner}/${repo}/rulesets`, trustRootRuleset);
+console.log('  ✓ trust-root 2-approval ruleset installed');
+console.log('Done.');

package/scripts/migrate-incident-2026-04-17.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+/**
+ * Day -2 prerequisite migration script for parallel-dev isolation.
+ *
+ * Per PARALLEL-DEV-ISOLATION-SPEC.md "Migration (iter 4 — Day -2 trust-boundary
+ * acknowledgment + GH ruleset auto-config)".
+ *
+ * Trust-on-first-use: this script CANNOT be verified by the system it installs
+ * (chicken-and-egg). The Day -2 PR ruleset entry requires 2 approvals on PRs
+ * touching .github/workflows/worktree-trailer-sig-check.yml so this lift
+ * happens with 4-eyes review.
+ *
+ * Steps:
+ *   1. Generate Ed25519 keypair (server-side; private to keychain).
+ *   2. Print public key for inspection (user pastes into workflow YAML).
+ *   3. Verify pre-existing stash@{0} matches expected SHA (refuse if changed).
+ *   4. After PR merges (and ruleset created via gh-ruleset-install.mjs),
+ *      write signed sentinel .instar/local-state/migration-2026-04-17.completed.
+ *
+ * Exit codes:
+ *   0 — completed (or sentinel already exists / nothing to do)
+ *   1 — refused (stash SHA mismatch / pre-condition failure)
+ *   2 — uncaught error
+ */
+
+import crypto from 'node:crypto';
+import { execSync, execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const ROOT = process.cwd();
+const STATE_DIR = path.join(ROOT, '.instar', 'local-state');
+const SENTINEL = path.join(STATE_DIR, 'migration-2026-04-17.completed');
+// Captured at spec-approval time; refuses migration if stash has changed since.
+const EXPECTED_STASH_REF = 'stash@{0}';
+const EXPECTED_STASH_LABEL_PREFIX = 'parallel-session: InitiativeTracker';
+
+function logStep(msg) {
+  console.log(`[migrate-incident-2026-04-17] ${msg}`);
+}
+
+function existsSentinel() {
+  return fs.existsSync(SENTINEL);
+}
+
+function generateKeypair() {
+  const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519', {
+    publicKeyEncoding: { type: 'spki', format: 'pem' },
+    privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+  });
+  return { publicKey, privateKey };
+}
+
+function verifyStash() {
+  let stashList;
+  try {
+    stashList = execSync('git stash list', { encoding: 'utf-8' });
+  } catch (err) {
+    logStep(`No stash present (or not a git repo). Skipping stash verification.`);
+    return { ok: true, skipped: true };
+  }
+  const lines = stashList.split('\n').filter(Boolean);
+  if (lines.length === 0) {
+    logStep('No stash entries — nothing to verify. Continuing.');
+    return { ok: true, skipped: true };
+  }
+  const top = lines[0];
+  if (!top.startsWith(`${EXPECTED_STASH_REF}:`)) {
+    return { ok: false, reason: `expected stash ref ${EXPECTED_STASH_REF}, got "${top}"` };
+  }
+  if (!top.includes(EXPECTED_STASH_LABEL_PREFIX)) {
+    return { ok: false, reason: `stash label changed; expected prefix "${EXPECTED_STASH_LABEL_PREFIX}", got "${top}"` };
+  }
+  return { ok: true };
+}
+
+function writeSentinel(publicKey, privateKey) {
+  fs.mkdirSync(STATE_DIR, { recursive: true });
+  // Sign the sentinel content with the new Ed25519 private key, anchoring future trust.
+  const sentinelContent = JSON.stringify({
+    completedAt: new Date().toISOString(),
+    publicKeyFingerprint: crypto.createHash('sha256').update(publicKey).digest('hex'),
+    schemaVersion: 1,
+  });
+  const signature = crypto.sign(null, Buffer.from(sentinelContent), { key: privateKey }).toString('base64');
+  fs.writeFileSync(SENTINEL, JSON.stringify({
+    content: sentinelContent,
+    signature,
+  }, null, 2), { mode: 0o600 });
+  logStep(`Wrote sentinel ${SENTINEL}`);
+}
+
+function main() {
+  if (existsSentinel()) {
+    logStep(`Sentinel exists at ${SENTINEL} — refusing to re-run.`);
+    process.exit(0);
+  }
+
+  logStep('Step 1: Generate Ed25519 keypair (server-side; private will go to keychain)');
+  const { publicKey, privateKey } = generateKeypair();
+
+  logStep('Step 2: Public key (paste into .github/workflows/worktree-trailer-sig-check.yml as `INSTAR_TRAILER_PUBLIC_KEY` repo variable):');
+  console.log('');
+  console.log(publicKey);
+  console.log('');
+
+  logStep('Step 3: Verify staged stash@{0} matches expected (refuse if changed)');
+  const stashCheck = verifyStash();
+  if (!stashCheck.ok) {
+    console.error(`[migrate-incident-2026-04-17] REFUSED: ${stashCheck.reason}`);
+    console.error('  → If you have intentionally moved the InitiativeTracker work, update EXPECTED_STASH_LABEL_PREFIX in this script.');
+    process.exit(1);
+  }
+  if (stashCheck.skipped) {
+    logStep('  (no stash to verify; this is expected after the InitiativeTracker work has been popped/dropped on this machine)');
+  }
+
+  logStep('Step 4: Write signed sentinel (anchors future trust to this acknowledged-TOFU root)');
+  writeSentinel(publicKey, privateKey);
+
+  // Save private key to a known transitional location for the user to register
+  // via `instar worktree register-keypair --private <path>` (which prompts for keychain).
+  const privPath = path.join(STATE_DIR, 'trailer-private-key.pem.NEW');
+  fs.writeFileSync(privPath, privateKey, { mode: 0o600 });
+  logStep(`Private key written to ${privPath} (chmod 0600)`);
+  logStep('  → Next: run `instar worktree register-keypair --private ' + privPath + '` to move into keychain.');
+  logStep('  → After successful registration, this file is securely deleted.');
+
+  logStep('DONE.');
+  process.exit(0);
+}
+
+try { main(); }
+catch (err) {
+  console.error(`[migrate-incident-2026-04-17] UNCAUGHT ${err.message}`);
+  console.error(err.stack);
+  process.exit(2);
+}

package/scripts/worktree-commit-msg-hook.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+/**
+ * worktree-commit-msg-hook.js — commit-msg hook for trailer signing.
+ *
+ * Invoked by git as: `worktree-commit-msg-hook.js <commit-msg-file>`.
+ *
+ * 1. Reads .instar/session-context.json (locates by walking up from cwd).
+ * 2. Computes treeHash via `git write-tree` (HONORS $GIT_INDEX_FILE per K-fix).
+ * 3. Reads parent SHA(s) via `git rev-parse HEAD` + merge-mode parents.
+ * 4. POSTs to instar server `/commits/sign-trailer`.
+ * 5. Appends 9 trailer lines via `git interpret-trailers --in-place`.
+ *
+ * Per spec section: "Commit trailer (iter 4 — Ed25519 + offline-friendly expiry + index-aware)".
+ *
+ * Exit codes:
+ *   0 — trailer injected (commit proceeds)
+ *   1 — failed; commit aborted with retry message
+ */
+
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import { execSync, execFileSync } from 'node:child_process';
+
+const SIGN_TIMEOUT_MS = 5000;
+
+function findSessionContext(startCwd) {
+  let cwd = startCwd;
+  for (let i = 0; i < 10; i++) {
+    const ctx = path.join(cwd, '.instar', 'session-context.json');
+    if (fs.existsSync(ctx)) return ctx;
+    const parent = path.dirname(cwd);
+    if (parent === cwd) break;
+    cwd = parent;
+  }
+  return null;
+}
+
+function gitParents(cwd) {
+  // Determine if this is a merge: presence of $GIT_REFLOG_ACTION=merge OR MERGE_HEAD file
+  const gitDir = execFileSync('git', ['-C', cwd, 'rev-parse', '--git-dir'], { encoding: 'utf-8' }).trim();
+  const mergeHeadPath = path.join(cwd, gitDir, 'MERGE_HEAD');
+  let parents = [];
+  // Primary parent = current HEAD (or 0...0 for initial commit)
+  try {
+    const head = execFileSync('git', ['-C', cwd, 'rev-parse', 'HEAD'], { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+    parents.push(head);
+  } catch {
+    parents.push('0'.repeat(40));
+  }
+  if (fs.existsSync(mergeHeadPath)) {
+    const extra = fs.readFileSync(mergeHeadPath, 'utf-8').trim().split('\n').filter(Boolean);
+    parents.push(...extra);
+  }
+  return parents;
+}
+
+function gitWriteTree(cwd) {
+  // K-fix: honor $GIT_INDEX_FILE (set by `git commit -a` and `git commit <file>`)
+  const env = { ...process.env };
+  return execFileSync('git', ['-C', cwd, 'write-tree', '--missing-ok'], {
+    encoding: 'utf-8', env,
+  }).trim();
+}
+
+function postSign({ serverUrl, authToken, sessionId, fencingToken, treeHash, parents }) {
+  return new Promise((resolve, reject) => {
+    const url = new URL(serverUrl);
+    const body = JSON.stringify({ sessionId, fencingToken, treeHash, parents });
+    const req = http.request({
+      method: 'POST',
+      hostname: url.hostname,
+      port: url.port,
+      path: '/commits/sign-trailer',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(body),
+        'Authorization': `Bearer ${authToken}`,
+      },
+      timeout: SIGN_TIMEOUT_MS,
+    }, (res) => {
+      let data = '';
+      res.on('data', (c) => data += c);
+      res.on('end', () => {
+        if (res.statusCode !== 200) return reject(new Error(`sign-trailer ${res.statusCode}: ${data}`));
+        try { resolve(JSON.parse(data)); }
+        catch (e) { reject(e); }
+      });
+    });
+    req.on('timeout', () => { req.destroy(); reject(new Error('sign-trailer timeout')); });
+    req.on('error', reject);
+    req.write(body);
+    req.end();
+  });
+}
+
+async function main() {
+  const commitMsgFile = process.argv[2];
+  if (!commitMsgFile) {
+    console.error('worktree-commit-msg-hook: usage: <commit-msg-file>');
+    process.exit(1);
+  }
+
+  // Skip merge commits authored by GitHub (they're verified at PR-merge time per spec)
+  // and skip rebase/cherry-pick (commit-msg re-fires per spec — handled the same way)
+  const cwd = process.cwd();
+  const ctxPath = findSessionContext(cwd);
+  if (!ctxPath) process.exit(0); // human commit, no session context
+
+  const ctx = JSON.parse(fs.readFileSync(ctxPath, 'utf-8'));
+  if (!ctx.sessionId || !ctx.fencingToken) process.exit(0);
+  if (ctx.mode === 'read-only') {
+    console.error('worktree-commit-msg-hook: BLOCK — read-only mode');
+    process.exit(1);
+  }
+
+  const serverUrl = process.env.INSTAR_SERVER_URL;
+  const authToken = process.env.INSTAR_AUTH_TOKEN;
+  if (!serverUrl || !authToken) {
+    console.error('worktree-commit-msg-hook: WARN — missing INSTAR_SERVER_URL; cannot sign trailer');
+    process.exit(0);
+  }
+
+  let treeHash;
+  try { treeHash = gitWriteTree(cwd); }
+  catch (err) {
+    console.error(`worktree-commit-msg-hook: BLOCK — write-tree failed: ${err.message}`);
+    process.exit(1);
+  }
+
+  const parents = gitParents(cwd);
+
+  let signed;
+  try {
+    signed = await postSign({
+      serverUrl, authToken,
+      sessionId: ctx.sessionId,
+      fencingToken: ctx.fencingToken,
+      treeHash,
+      parents,
+    });
+  } catch (err) {
+    console.error(`worktree-commit-msg-hook: BLOCK — sign-trailer failed: ${err.message}`);
+    console.error('  Retry the commit; or run `instar worktree status` to diagnose.');
+    process.exit(1);
+  }
+
+  // Append trailers via git interpret-trailers --in-place
+  const trailerArgs = [];
+  for (const t of signed.trailers) {
+    trailerArgs.push('--trailer', t);
+  }
+  try {
+    execFileSync('git', ['interpret-trailers', '--in-place', ...trailerArgs, commitMsgFile], {
+      stdio: 'inherit',
+    });
+  } catch (err) {
+    console.error(`worktree-commit-msg-hook: BLOCK — interpret-trailers failed: ${err.message}`);
+    process.exit(1);
+  }
+
+  process.exit(0);
+}
+
+main().catch((err) => {
+  console.error(`worktree-commit-msg-hook: BLOCK — ${err.message}`);
+  process.exit(1);
+});