instar 1.3.1611 → 1.3.1613

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.1611",
+  "version": "1.3.1613",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/scripts/build-locked-proof.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+// safe-git-allow: read-only git (rev-parse, show, archive) and removal of the build's own node_modules link inside its scratch tree; nothing in a checkout is changed.
+/**
+ * build-locked-proof.mjs — the locked-screen TEST BUILD (docs/specs/desktop-locked-screen.md,
+ * phase 3: "That build alone compiles in a test proven-versions table").
+ *
+ * It copies one committed revision into a scratch directory OUTSIDE this checkout,
+ * adds a single `PROOF-RUN-IN-PROGRESS` row for one macOS major version to the
+ * scratch copy of src/core/DesktopProvenVersions.ts, sets the package version to
+ * `<release>-lockedproof.<n>`, builds it (TypeScript + the unchanged Swift helper)
+ * and packs it. The committed table is never touched, nothing is published, and
+ * the helper source is the shipped one, so its source hash binds the proof
+ * evidence to the helper the fleet will run.
+ *
+ * Usage:
+ *   node scripts/build-locked-proof.mjs [--os-major N] [--n N] [--ref REF] [--out DIR] [--dry-run]
+ *
+ *   --os-major  macOS major to admit (default: this Mac's `sw_vers -productVersion`)
+ *   --n         build number for the version suffix (default 1)
+ *   --ref       git revision to build (default HEAD; committed content only)
+ *   --out       where the scratch tree, .tgz and manifest go (default $TMPDIR/instar-locked-proof)
+ *   --dry-run   stop after the rewrite: print the row and the diff, build nothing
+ *
+ * Output: `<out>/instar-<version>.tgz` and `<out>/locked-proof-manifest-<version>.json`
+ * ({ packageVersion, commit, osMajor, helperSourceHash, tgz, tgzSha256, createdAt }).
+ * Install only into a throwaway macOS user's own prefix, with auto-update off.
+ */
+import { execFileSync } from 'node:child_process';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseOsMajor, proofVersion, rewriteProvenTable } from './lib/locked-proof-build.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const TABLE_FILE = 'src/core/DesktopProvenVersions.ts';
+
+function arg(name) {
+  const i = process.argv.indexOf(`--${name}`);
+  return i >= 0 ? process.argv[i + 1] : undefined;
+}
+const dryRun = process.argv.includes('--dry-run');
+
+function git(args, opts = {}) {
+  return execFileSync('git', args, { cwd: ROOT, encoding: 'utf8', ...opts });
+}
+
+function localOsMajor() {
+  if (process.platform !== 'darwin') throw new Error('--os-major is required when not running on a Mac');
+  return parseOsMajor(execFileSync('sw_vers', ['-productVersion'], { encoding: 'utf8' }));
+}
+
+function main() {
+  const osMajor = arg('os-major') !== undefined ? parseOsMajor(arg('os-major')) : localOsMajor();
+  const n = arg('n') !== undefined ? Number.parseInt(arg('n'), 10) : 1;
+  const ref = arg('ref') ?? 'HEAD';
+  const out = path.resolve(arg('out') ?? path.join(os.tmpdir(), 'instar-locked-proof'));
+  const commit = git(['rev-parse', '--verify', `${ref}^{commit}`]).trim();
+  if (out === ROOT || out.startsWith(ROOT + path.sep)) throw new Error(`--out must be outside this checkout (${ROOT})`);
+
+  const committedTable = git(['show', `${commit}:${TABLE_FILE}`]);
+  const basePkg = JSON.parse(git(['show', `${commit}:package.json`]));
+  const version = proofVersion(basePkg.version, n);
+  const rewritten = rewriteProvenTable(committedTable, { osMajor, version });
+
+  const tableHashBefore = fs.existsSync(path.join(ROOT, TABLE_FILE))
+    ? crypto.createHash('sha256').update(fs.readFileSync(path.join(ROOT, TABLE_FILE))).digest('hex') : null;
+
+  if (dryRun) {
+    console.log(`[locked-proof] dry run: ${version} at ${commit.slice(0, 12)} admits macOS ${osMajor}`);
+    console.log(rewritten.split('\n').filter(line => line.includes('PROVEN_MACOS_VERSIONS')).join('\n'));
+    return;
+  }
+
+  const scratch = path.join(out, `instar-${version}`);
+  if (fs.existsSync(scratch)) throw new Error(`${scratch} exists; pick another --n or remove it`);
+  fs.mkdirSync(scratch, { recursive: true });
+
+  // Committed content only: an uncommitted edit in this checkout never reaches the build.
+  const archive = execFileSync('git', ['archive', '--format=tar', commit], { cwd: ROOT, maxBuffer: 1 << 30 });
+  execFileSync('tar', ['-x', '-C', scratch], { input: archive, maxBuffer: 1 << 30 });
+
+  fs.writeFileSync(path.join(scratch, TABLE_FILE), rewritten);
+  const pkg = JSON.parse(fs.readFileSync(path.join(scratch, 'package.json'), 'utf8'));
+  pkg.version = version;
+  fs.writeFileSync(path.join(scratch, 'package.json'), `${JSON.stringify(pkg, null, 2)}\n`);
+  fs.symlinkSync(path.join(ROOT, 'node_modules'), path.join(scratch, 'node_modules'));
+
+  console.log(`[locked-proof] building ${version} (macOS ${osMajor}) in ${scratch}`);
+  // Never release-signed: the lock-file signer reads these env keys (and a local .instar-release-keys/, which a
+  // fresh git archive never contains), and a test build must not carry a release signature.
+  const buildEnv = { ...process.env };
+  delete buildEnv.INSTAR_RELEASE_PRIVATE_KEY_PEM;
+  delete buildEnv.INSTAR_RELEASE_PRIVATE_KEY_PEM_PATH;
+  delete buildEnv.INSTAR_RELEASE_BUILD;
+  execFileSync('npm', ['run', 'build'], { cwd: scratch, stdio: 'inherit', env: buildEnv });
+  // The symlink must not be packed; npm pack ignores node_modules, but drop it to be sure.
+  fs.unlinkSync(path.join(scratch, 'node_modules'));
+  const packed = execFileSync('npm', ['pack', '--ignore-scripts', '--pack-destination', out], { cwd: scratch, encoding: 'utf8' })
+    .trim().split('\n').pop();
+  const tgz = path.join(out, packed);
+
+  const helper = JSON.parse(fs.readFileSync(path.join(scratch, 'dist/native/instar-desktop-host.json'), 'utf8'));
+  const manifest = {
+    packageVersion: version, commit, osMajor, helperSourceHash: helper.sourceHash,
+    tgz, tgzSha256: crypto.createHash('sha256').update(fs.readFileSync(tgz)).digest('hex'),
+    createdAt: new Date().toISOString(),
+  };
+  const manifestPath = path.join(out, `locked-proof-manifest-${version}.json`);
+  fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+
+  const tableHashAfter = fs.existsSync(path.join(ROOT, TABLE_FILE))
+    ? crypto.createHash('sha256').update(fs.readFileSync(path.join(ROOT, TABLE_FILE))).digest('hex') : null;
+  if (tableHashBefore !== tableHashAfter) throw new Error(`${TABLE_FILE} in this checkout changed during the build`);
+
+  console.log(`[locked-proof] ${tgz}`);
+  console.log(`[locked-proof] manifest ${manifestPath}`);
+  console.log(`[locked-proof] helper sourceHash ${helper.sourceHash}`);
+}
+
+try { main(); } catch (err) {
+  console.error(`[locked-proof] ${err instanceof Error ? err.message : String(err)}`);
+  process.exit(1);
+}

package/scripts/lib/locked-proof-build.mjs

@@ -0,0 +1,71 @@
+/**
+ * Pure helpers for scripts/build-locked-proof.mjs (docs/specs/desktop-locked-screen.md,
+ * phase 3 "test build"). Kept separate so the rewrite is unit-tested without a build.
+ *
+ * The test build is the ONLY way a macOS version without recorded P12/P15 passes
+ * reaches the proven-versions table, and it only ever does so in a scratch copy.
+ */
+
+/** The marker every test-build row carries instead of a proof path. */
+export const PROOF_IN_PROGRESS = 'PROOF-RUN-IN-PROGRESS';
+
+/** The literal the committed table is declared with. Exactly one must exist. */
+const TABLE_RE = /export const PROVEN_MACOS_VERSIONS: readonly DesktopProvenVersion\[\] = Object\.freeze\(\[([\s\S]*?)\]\);/g;
+
+/** `<base>-lockedproof.<n>`; base must be a plain dotted release version. */
+export function proofVersion(base, n) {
+  if (typeof base !== 'string' || !/^\d+\.\d+\.\d+$/.test(base)) {
+    throw new Error(`package version "${base}" is not a plain release version (x.y.z)`);
+  }
+  if (!Number.isSafeInteger(n) || n < 1) throw new Error(`build number must be a positive integer, got ${n}`);
+  return `${base}-lockedproof.${n}`;
+}
+
+export function parseOsMajor(value) {
+  const major = Number.parseInt(String(value).trim().split('.')[0] ?? '', 10);
+  if (!Number.isSafeInteger(major) || major < 11 || major > 99) {
+    throw new Error(`not a macOS major version: "${value}"`);
+  }
+  return major;
+}
+
+/**
+ * Return the source of DesktopProvenVersions.ts with one test row for `osMajor`
+ * added in front of the committed rows. Refuses when the declaration is not
+ * found exactly once, or when that version is already in the table.
+ */
+export function rewriteProvenTable(source, { osMajor, version }) {
+  const matches = [...source.matchAll(TABLE_RE)];
+  if (matches.length !== 1) {
+    throw new Error(`expected exactly one PROVEN_MACOS_VERSIONS declaration, found ${matches.length}`);
+  }
+  const [whole, body] = matches[0];
+  if (new RegExp(`osMajor:\\s*${osMajor}\\b`).test(body)) {
+    throw new Error(`macOS ${osMajor} is already in the committed table; no test build is needed`);
+  }
+  const marker = `${PROOF_IN_PROGRESS} ${version}`;
+  const row = `{ osMajor: ${osMajor}, p12: '${marker}', p15: '${marker}', refuse: [] }`;
+  const rest = body.trim();
+  const next = whole.replace(`([${body}])`, `([${row}${rest ? `, ${rest}` : ''}])`);
+  return source.replace(whole, next);
+}
+
+/**
+ * Check a table's rows against the proof records on disk. A committed row must
+ * cite, for p12 and p15, a file under docs/proofs/desktop-locked-screen/ that
+ * exists (an `#anchor` is allowed), and never the test-build marker.
+ * Returns a list of problems (empty when every row is backed).
+ */
+export function unprovenRows(rows, fileExists) {
+  const problems = [];
+  for (const row of rows) {
+    for (const gate of ['p12', 'p15']) {
+      const cite = String(row[gate] ?? '');
+      const file = cite.split('#')[0];
+      if (cite.includes(PROOF_IN_PROGRESS)) problems.push(`macOS ${row.osMajor} ${gate}: test-build marker in the committed table`);
+      else if (!file.startsWith('docs/proofs/desktop-locked-screen/') || file.includes('..')) problems.push(`macOS ${row.osMajor} ${gate}: "${cite}" is not a proof record path`);
+      else if (!fileExists(file)) problems.push(`macOS ${row.osMajor} ${gate}: proof record ${file} does not exist`);
+    }
+  }
+  return problems;
+}

package/scripts/locked-proof/configure-proof-agent.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+/**
+ * Set a proof agent's config for the locked-Mac proof run. Runs as the proof user.
+ *
+ *   configure-proof-agent.mjs <agent-dir> --port N [--tunnel] [--front] --execute
+ *
+ * Without --execute it prints what it would change. It refuses any directory that
+ * does not resolve inside /Users/instarproof (the throwaway proof user's home).
+ *
+ * - remote desktop on, the kept helper on (the proof user's own copy), locked-screen
+ *   access left absent (off): the run turns it on with the dashboard PIN route.
+ * - updates never auto-applied: the updater would replace the -lockedproof build.
+ * - no start-on-login job: the driver starts and stops the server itself.
+ * - --tunnel: a Cloudflare quick tunnel (the password box needs a first-tier tunnel).
+ * - --front: this agent is its own designated desktop front (needs the machine id,
+ *   which exists after the first server start; run again with --front then).
+ * Only missing or listed keys change; everything else in config.json is kept.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const PROOF_HOME = '/Users/instarproof';
+
+/** True only for a resolved path inside the proof user's home. */
+export function isInsideProofHome(resolved) {
+  return resolved === PROOF_HOME || resolved.startsWith(`${PROOF_HOME}/`);
+}
+
+export function proofConfig(config, { port, tunnel, frontMachineId }) {
+  const next = { ...config, port };
+  next.remoteDesktop = { ...(config.remoteDesktop ?? {}), enabled: true, retainedHelper: true };
+  if (frontMachineId) next.remoteDesktop.frontMachineId = frontMachineId;
+  delete next.remoteDesktop.lockedScreen;
+  next.updates = { ...(config.updates ?? {}), autoApply: false };
+  next.autostart = { ...(config.autostart ?? {}), autoInstall: false };
+  next.messaging = [];
+  if (tunnel) next.tunnel = { ...(config.tunnel ?? {}), enabled: true, type: 'quick' };
+  else if (next.tunnel) next.tunnel = { ...next.tunnel, enabled: false };
+  return next;
+}
+
+function main() {
+  const [dir, ...rest] = process.argv.slice(2);
+  const opt = name => { const i = rest.indexOf(`--${name}`); return i >= 0 ? rest[i + 1] : undefined; };
+  const port = Number(opt('port'));
+  if (!dir || !Number.isSafeInteger(port)) { process.stderr.write('usage: configure-proof-agent.mjs <agent-dir> --port N [--tunnel] [--front]\n'); process.exit(2); }
+  const real = fs.realpathSync(dir);
+  if (!isInsideProofHome(real)) { process.stderr.write(`refusing: ${real} is not inside ${PROOF_HOME}\n`); process.exit(1); }
+  const file = path.join(real, '.instar', 'config.json');
+  const config = JSON.parse(fs.readFileSync(file, 'utf8'));
+  let frontMachineId;
+  if (rest.includes('--front')) {
+    const identity = path.join(real, '.instar', 'machine', 'identity.json');
+    if (!fs.existsSync(identity)) { process.stderr.write('no machine identity yet: start the server once, then run with --front\n'); process.exit(1); }
+    frontMachineId = JSON.parse(fs.readFileSync(identity, 'utf8')).machineId;
+  }
+  const next = proofConfig(config, { port, tunnel: rest.includes('--tunnel'), frontMachineId });
+  if (!rest.includes('--execute')) {
+    process.stdout.write(`dry run (no --execute): would write ${file}\n${JSON.stringify({ port: next.port, remoteDesktop: next.remoteDesktop, updates: next.updates, autostart: next.autostart, tunnel: next.tunnel ?? null })}\n`);
+    return;
+  }
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+  fs.renameSync(tmp, file);
+  process.stdout.write(`configured ${dir} (port ${port}${rest.includes('--tunnel') ? ', quick tunnel' : ''}${frontMachineId ? `, front ${frontMachineId}` : ''})\n`);
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === new URL(import.meta.url).pathname) main();

package/scripts/locked-proof/create-proof-user.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# Create the throwaway macOS user for the locked-Mac proof run (instarproof).
+#
+#   create-proof-user.sh --agent-home DIR [--execute] [--replace-vault]
+#
+# Without --execute it only prints the plan. With --execute (run as an admin with
+# passwordless sudo, on the proof Mac):
+#   1. generates a throwaway password (20 lowercase letters/digits, layout-safe),
+#   2. stores it in the agent's vault FIRST (credential-store.mjs, value on stdin),
+#      under key locked_proof_user_password, so no password exists that the vault lacks.
+#      credential-store.mjs writes Bitwarden first; this script refuses to run unless that
+#      helper hands Bitwarden the encoded item on stdin (an older copy put it on `bw`'s
+#      command line, where `ps` can read it),
+#   3. creates the standard (non-admin) user with sysadminctl, answering its password
+#      prompt through a pseudo-terminal (never on a command line, never in a log),
+#   4. clears the user's account policies, so macOS does not force a password change
+#      at first login and does not lock the account after failed attempts,
+#   5. checks the stored password authenticates (dscl -authonly, again by prompt).
+# The password is never printed. Remove everything with remove-proof-user.sh.
+#
+# Tests point LOCKED_PROOF_FAKE_BIN at stand-in commands; then sudo is not used.
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROOF_USER="instarproof"
+VAULT_KEY="locked_proof_user_password"
+AGENT_HOME=""
+EXECUTE=0
+REPLACE=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --agent-home) AGENT_HOME="$2"; shift 2 ;;
+    --execute) EXECUTE=1; shift ;;
+    --replace-vault) REPLACE=1; shift ;;
+    *) echo "unknown option: $1" >&2; exit 2 ;;
+  esac
+done
+[ -n "$AGENT_HOME" ] || { echo "--agent-home is required" >&2; exit 2; }
+
+if [ -n "${LOCKED_PROOF_FAKE_BIN:-}" ]; then
+  SUDO=""; BIN="$LOCKED_PROOF_FAKE_BIN"
+  SYSADMINCTL="$BIN/sysadminctl"; DSCL="$BIN/dscl"; PWPOLICY="$BIN/pwpolicy"; STORE="$BIN/credential-store"
+else
+  SUDO="sudo -n"
+  SYSADMINCTL="/usr/sbin/sysadminctl"; DSCL="/usr/bin/dscl"; PWPOLICY="/usr/bin/pwpolicy"
+  STORE="node $AGENT_HOME/.instar/scripts/credential-store.mjs"
+fi
+
+HOST_LABEL="$(scutil --get ComputerName 2>/dev/null || hostname)"
+echo "Plan: create standard user '$PROOF_USER' on $HOST_LABEL; password generated here, stored in the vault of $AGENT_HOME as '$VAULT_KEY' (and Bitwarden) before the user exists; account policies cleared (no forced change at first login)."
+if [ "$EXECUTE" -ne 1 ]; then
+  echo "Dry run: nothing done. Add --execute on the proof Mac to do it."
+  exit 0
+fi
+
+if [ -z "${LOCKED_PROOF_FAKE_BIN:-}" ]; then
+  [ "$(uname -s)" = "Darwin" ] || { echo "macOS only" >&2; exit 1; }
+  sudo -n true 2>/dev/null || { echo "needs passwordless sudo" >&2; exit 1; }
+fi
+if $DSCL . -read "/Users/$PROOF_USER" UniqueID >/dev/null 2>&1; then
+  echo "user $PROOF_USER already exists; remove it first (remove-proof-user.sh)" >&2
+  exit 1
+fi
+
+HELPER="$AGENT_HOME/.instar/scripts/credential-store.mjs"
+if [ -z "${LOCKED_PROOF_FAKE_BIN:-}" ] && [ ! -f "$HELPER" ]; then echo "no $HELPER" >&2; exit 1; fi
+if [ -f "$HELPER" ]; then
+  if grep -Eq "bw\(\['(create', 'item'|edit', 'item', [a-z.]+), bw\(" "$HELPER"; then
+    echo "refusing: $HELPER puts the encoded Bitwarden item on bw's command line; update it to pass it on stdin first" >&2
+    exit 1
+  fi
+fi
+
+PW="$(node --input-type=module -e "import { generateProofPassword } from '$HERE/lib.mjs'; process.stdout.write(generateProofPassword());")"
+[ "${#PW}" -eq 20 ] || { echo "password generation failed" >&2; exit 1; }
+
+FORCE_ARG=""
+[ "$REPLACE" -eq 1 ] && FORCE_ARG="--force"
+# printf is a shell builtin: the value is never an argument of any process.
+printf '%s' "$PW" | (cd "$AGENT_HOME" && $STORE "$VAULT_KEY" --bw-name "Instar locked-proof test user ($HOST_LABEL)" \
+  --bw-user "$PROOF_USER" --bw-note "Throwaway macOS user for the locked-screen proof run. Delete with the user." $FORCE_ARG)
+echo "stored in the vault as $VAULT_KEY"
+
+printf '%s' "$PW" | $SUDO python3 "$HERE/pty-feed.py" --prompts 2 --timeout 120 -- \
+  $SYSADMINCTL -addUser "$PROOF_USER" -fullName "Instar proof" -password -
+$SUDO $PWPOLICY -u "$PROOF_USER" -clearaccountpolicies >/dev/null
+printf '%s' "$PW" | $SUDO python3 "$HERE/pty-feed.py" --prompts 1 --timeout 30 -- $DSCL . -authonly "$PROOF_USER"
+unset PW
+echo "created $PROOF_USER; the stored password authenticates"