instar 1.3.1665 → 1.3.1666

package/dist/data/standards-guard-index.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "generatedFrom": "source-tree",
   "registrySha256": "f91273af3f6f22eb6bb3161c35b109469d8457f1f93b2ec90eec9e58f62ead53",
-  "packageVersion": "1.3.1665",
+  "packageVersion": "1.3.1666",
   "guards": [
     {
       "ref": "docs/audits/phase-b/f10-triage.md",

package/dist/data/standards-guard-index.meta.json

@@ -1,5 +1,5 @@
 {
-  "sha256": "fa0889edea392faf22e071678dfc99ab29a790b3018cd8226791bff29c72eda5",
+  "sha256": "f58de796ebb089dbbc16199d4d4e7adb68bc81b328fb344e26b66d36ff78cf75",
   "registrySha256": "f91273af3f6f22eb6bb3161c35b109469d8457f1f93b2ec90eec9e58f62ead53",
-  "packageVersion": "1.3.1665"
+  "packageVersion": "1.3.1666"
 }

package/dist/data/standards-registry.meta.json

@@ -2,5 +2,5 @@
   "sha256": "f91273af3f6f22eb6bb3161c35b109469d8457f1f93b2ec90eec9e58f62ead53",
   "articleCount": 95,
   "generatedFrom": "docs/STANDARDS-REGISTRY.md",
-  "packageVersion": "1.3.1665"
+  "packageVersion": "1.3.1666"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.1665",
+  "version": "1.3.1666",
   "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

@@ -13,16 +13,20 @@
  * 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]
+ *   node scripts/build-locked-proof.mjs [--os-major N] [--n N] [--ref REF] [--out DIR] [--helper-dir NAME] [--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)
+ *   --helper-dir  keep the helper in ~/.instar/NAME (desktop-helper-<name>) in this build only. For a proof Mac
+ *               whose macOS permission row at the default folder names an older build: that row can be neither
+ *               seen nor cleared, and a new path has none. The helper source, and so its hash, stays the same.
  *   --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 }).
+ * ({ packageVersion, commit, osMajor, helperSourceHash, helperDir, tgz, tgzSha256, createdAt }).
+ * On a Mac the helper is universal: only a universal helper may take the kept copy.
  * Install only into a throwaway macOS user's own prefix, with auto-update off.
  */
 import { execFileSync } from 'node:child_process';
@@ -31,10 +35,12 @@ 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';
+import { parseOsMajor, proofVersion, rewriteHelperRoot, rewriteProvenTable } from './lib/locked-proof-build.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const TABLE_FILE = 'src/core/DesktopProvenVersions.ts';
+const RETENTION_FILE = 'src/core/DesktopHelperRetention.ts';
+const FAT_MAGIC = 0xcafebabe;
 
 function arg(name) {
   const i = process.argv.indexOf(`--${name}`);
@@ -63,6 +69,9 @@ function main() {
   const basePkg = JSON.parse(git(['show', `${commit}:package.json`]));
   const version = proofVersion(basePkg.version, n);
   const rewritten = rewriteProvenTable(committedTable, { osMajor, version });
+  const helperDir = arg('helper-dir');
+  const rewrittenRetention = helperDir === undefined ? null
+    : rewriteHelperRoot(git(['show', `${commit}:${RETENTION_FILE}`]), helperDir);
 
   const tableHashBefore = fs.existsSync(path.join(ROOT, TABLE_FILE))
     ? crypto.createHash('sha256').update(fs.readFileSync(path.join(ROOT, TABLE_FILE))).digest('hex') : null;
@@ -70,6 +79,7 @@ function main() {
   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'));
+    if (rewrittenRetention) console.log(rewrittenRetention.split('\n').filter(line => line.includes(helperDir)).join('\n'));
     return;
   }
 
@@ -82,6 +92,7 @@ function main() {
   execFileSync('tar', ['-x', '-C', scratch], { input: archive, maxBuffer: 1 << 30 });
 
   fs.writeFileSync(path.join(scratch, TABLE_FILE), rewritten);
+  if (rewrittenRetention) fs.writeFileSync(path.join(scratch, RETENTION_FILE), rewrittenRetention);
   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`);
@@ -95,6 +106,16 @@ function main() {
   delete buildEnv.INSTAR_RELEASE_PRIVATE_KEY_PEM_PATH;
   delete buildEnv.INSTAR_RELEASE_BUILD;
   execFileSync('npm', ['run', 'build'], { cwd: scratch, stdio: 'inherit', env: buildEnv });
+  if (process.platform === 'darwin') {
+    // Retention keeps only a universal helper, and a plain build is thin. Only this native step sees the flag, so
+    // the lock-file signer above still ran without it.
+    execFileSync('node', ['scripts/build-native-desktop-host.mjs'], { cwd: scratch, stdio: 'inherit', env: { ...buildEnv, INSTAR_RELEASE_BUILD: '1' } });
+    const head = Buffer.alloc(4);
+    const handle = fs.openSync(path.join(scratch, 'dist/native/instar-desktop-host'), 'r');
+    fs.readSync(handle, head, 0, 4, 0);
+    fs.closeSync(handle);
+    if (head.readUInt32BE(0) !== FAT_MAGIC) throw new Error('the helper did not come out universal, so it could never be kept');
+  }
   // 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' })
@@ -103,7 +124,7 @@ function main() {
 
   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,
+    packageVersion: version, commit, osMajor, helperSourceHash: helper.sourceHash, helperDir: helperDir ?? 'desktop-helper',
     tgz, tgzSha256: crypto.createHash('sha256').update(fs.readFileSync(tgz)).digest('hex'),
     createdAt: new Date().toISOString(),
   };

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

@@ -50,6 +50,27 @@ export function rewriteProvenTable(source, { osMajor, version }) {
   return source.replace(whole, next);
 }
 
+/** The exact default the retained helper's folder is declared with. */
+const HELPER_ROOT_DEFAULT = "path.join(os.homedir(), '.instar', 'desktop-helper')";
+
+/**
+ * Return the source of DesktopHelperRetention.ts with the kept helper's default
+ * folder moved to `~/.instar/<dir>`. macOS keeps a permission row per path, and
+ * neither Settings nor tccutil can clear a hidden row for a bare program, so a
+ * proof Mac whose row names an older build needs a path with no row. The Swift
+ * source is untouched, so the helper source hash that binds the proof is too.
+ * Refuses when the default is not found exactly once, or for a name that could
+ * land inside the locked store or outside `~/.instar`.
+ */
+export function rewriteHelperRoot(source, dir) {
+  if (typeof dir !== 'string' || !/^desktop-helper-[a-z0-9-]+$/.test(dir)) {
+    throw new Error(`helper folder "${dir}" must look like desktop-helper-<name>`);
+  }
+  const found = source.split(HELPER_ROOT_DEFAULT).length - 1;
+  if (found !== 1) throw new Error(`expected exactly one default helper folder, found ${found}`);
+  return source.replace(HELPER_ROOT_DEFAULT, `path.join(os.homedir(), '.instar', '${dir}')`);
+}
+
 /**
  * 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

package/scripts/locked-proof/driver.mjs

@@ -72,6 +72,20 @@ export function setupGaps(agents) {
 /** The login name owning a pid, or '' when it is gone. */
 export function ownerOf(pid) { return sh('ps', ['-o', 'user=', '-p', String(pid)], { allowFail: true }).trim(); }
 
+/**
+ * Sends one person step and writes down whether it went. A refused send used to
+ * vanish, so a person was never told and the case simply timed out; now the
+ * refusal is in person-steps.jsonl and on stderr for whoever is watching the run.
+ */
+export function recordPersonStep(o, text, send) {
+  const result = o.notifyTopic ? send() : null;
+  const sent = result ? result.status === 0 : false;
+  const row = { at: new Date().toISOString(), text, topic: o.notifyTopic ?? null, sent };
+  fs.appendFileSync(path.join(o.out, 'person-steps.jsonl'), `${JSON.stringify(row)}\n`);
+  if (o.notifyTopic && !sent) process.stderr.write(`[locked-proof] person step NOT delivered to topic ${o.notifyTopic}: ${text}\n`);
+  return row;
+}
+
 /** The proof Mac, the proof user, its two agents and the real viewer page. */
 export class RealTarget {
   constructor(o) {
@@ -363,10 +377,9 @@ export class RealTarget {
 
   async askPerson(text) {
     process.stdout.write(`\n>>> PERSON STEP: ${text}\n\n`);
-    if (this.o.notifyTopic) {
-      sh('bash', [path.join(this.o.agentHome, '.instar/scripts/telegram-reply.sh'), String(this.o.notifyTopic)],
-        { input: `Locked-Mac proof: ${text}`, allowFail: true });
-    }
+    recordPersonStep(this.o, text, () => spawnSync('bash',
+      [path.join(this.o.agentHome, '.instar/scripts/telegram-reply.sh'), String(this.o.notifyTopic)],
+      { encoding: 'utf8', input: `Locked-Mac proof: ${text}`, timeout: 30_000 }));
   }
 
   async extraEvidence(c, ev) {

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-11-05T04:47:26.740Z",
-  "instarVersion": "1.3.1665",
+  "generatedAt": "2026-11-05T05:26:43.534Z",
+  "instarVersion": "1.3.1666",
   "entryCount": 206,
   "entries": {
     "hook:session-start": {

package/src/data/standards-guard-index.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "generatedFrom": "source-tree",
   "registrySha256": "f91273af3f6f22eb6bb3161c35b109469d8457f1f93b2ec90eec9e58f62ead53",
-  "packageVersion": "1.3.1665",
+  "packageVersion": "1.3.1666",
   "guards": [
     {
       "ref": "docs/audits/phase-b/f10-triage.md",

package/src/data/standards-guard-index.meta.json

@@ -1,5 +1,5 @@
 {
-  "sha256": "fa0889edea392faf22e071678dfc99ab29a790b3018cd8226791bff29c72eda5",
+  "sha256": "f58de796ebb089dbbc16199d4d4e7adb68bc81b328fb344e26b66d36ff78cf75",
   "registrySha256": "f91273af3f6f22eb6bb3161c35b109469d8457f1f93b2ec90eec9e58f62ead53",
-  "packageVersion": "1.3.1665"
+  "packageVersion": "1.3.1666"
 }

package/src/data/standards-registry.meta.json

@@ -2,5 +2,5 @@
   "sha256": "f91273af3f6f22eb6bb3161c35b109469d8457f1f93b2ec90eec9e58f62ead53",
   "articleCount": 95,
   "generatedFrom": "docs/STANDARDS-REGISTRY.md",
-  "packageVersion": "1.3.1665"
+  "packageVersion": "1.3.1666"
 }

package/upgrades/1.3.1666.md

@@ -0,0 +1,16 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The locked-Mac proof build can keep its helper in a separate folder for one test build, so a hidden macOS permission record at the usual folder no longer blocks a proof. The proof build now always makes a helper that can be kept, and the proof driver records whether each person step was delivered. Nothing that ships to agents changes.
+
+## What to Tell Your User
+
+None — internal change (no user-facing surface).
+
+## Summary of New Capabilities
+
+None — internal change (no user-facing surface).

package/upgrades/locked-proof-helper-dir.eli16.md

@@ -0,0 +1,11 @@
+# Moving the test helper to a clean spot (plain version)
+
+We are proving that Remote Desktop can open a locked Mac. The test on the Mac Mini is stuck for a boring reason. macOS remembers permissions by the program's location, and the memory at the current location describes an older copy of the helper. Nobody can see that record in System Settings, and the usual tool for clearing records refuses programs like ours.
+
+What is new: the script that makes the test build can now put the helper in a different folder, for that one test build only. A folder macOS has never seen has no old record to trip over. The helper program itself does not change, so what we prove still applies to the helper we ship.
+
+Two small repairs ride along. The test build now always makes the kind of helper that can be kept, which used to need a manual step. And the test driver now writes down whether each "please do this at the Mac" message was really delivered, because a refused message used to disappear silently while the test waited.
+
+Nothing here changes what ships to any agent. The real product problem, that a changed helper can leave a hidden record behind, is still open and tracked in the feedback queue. This is the way past it for the proof, and it is also the way we find out whether a clean location really works.
+
+There is nothing for anyone to decide here. If it turns out wrong, reverting the commit puts everything back.

package/upgrades/side-effects/locked-proof-helper-dir.md

@@ -0,0 +1,52 @@
+# Side-Effects Review: locked-proof build can move the helper folder
+
+**Version / slug:** `locked-proof-helper-dir`
+**Date:** `2026-11-04`
+**Author:** `Echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+Tier 1, test harness only: 5 files, about 90 lines, one review round, nothing under `src/` changes.
+
+The locked-Mac proof is stuck on the Mac Mini. macOS keeps a permission row per program path, and the row at the kept helper's path names an older build. The row is invisible in System Settings, the plus button leaves its old requirement in place, and `tccutil` refuses a bare program. So:
+
+1. `scripts/build-locked-proof.mjs --helper-dir desktop-helper-<name>` moves the kept helper's default folder, in the scratch copy of one test build only. The manifest records `helperDir`.
+2. The same script now always makes a universal helper on a Mac. Retention keeps only a universal helper, and the last three proof builds needed a hand-run extra step for this.
+3. `driver.mjs` writes every person step to `person-steps.jsonl` with whether it was delivered, and says so on stderr when it was not. A refused send used to vanish while the case timed out.
+
+## Decision-point inventory
+
+None added to any shipped path. `rewriteHelperRoot` refuses bad input at build time on a developer's Mac. `recordPersonStep` records a fact and blocks nothing.
+
+## 1. Over-block
+
+`--helper-dir` accepts only `desktop-helper-<lowercase name>`. That is deliberate, and no legitimate use needs more.
+
+## 2. Under-block
+
+A build moved to a new folder still needs one person trip for the grant. If macOS writes a stale requirement at a fresh path too, this does not help; the proof sitting measures that. The shipped product still has the stale-row dead end after a helper source change. That is tracked in feedback fb-a67570d1-f1d and fb-f21f34ff-491 and is not fixed here.
+
+## 3. Level-of-abstraction fit
+
+Right layer. The build script already rewrites a scratch copy for the proven-versions table. A config key would add a shipped option that only a proof needs.
+
+## 4. Signal vs authority compliance
+
+No blocking authority is added. The person-step record is a pure signal. Reference: `docs/signal-vs-authority.md`.
+
+## 5. Interactions
+
+The locked store stays at `~/.instar/desktop-helper/locked` (`DesktopLockedController`), and `driver.mjs` and `reset-attempts.py` pin that store, so they keep working. `resolve()` treats a new folder as a first grant.
+
+## 6. External surfaces
+
+None for users or other agents. Only `-lockedproof` builds, which are never published, can carry the moved folder.
+
+## 7. Multi-machine posture
+
+Machine-local: one build for one proof Mac. Nothing is replicated.
+
+## 8. Rollback cost
+
+Revert the commit. Without the flag the build output is as before, except that the helper is universal on a Mac.