instar 1.0.13 → 1.1.1

package/scripts/lint-no-direct-destructive.js

@@ -469,6 +469,13 @@ const SHELL_ALLOWLIST = new Set([
   // ports this to a Node script that uses SafeGitExecutor and removes this
   // entry.
   'src/templates/scripts/git-sync-gate.sh',
+  // Wrapper installed into every agent's `.bin/`. Primary path delegates
+  // to `instar worktree create` (which uses SafeGitExecutor). The inline
+  // fallback at the bottom of the file runs only when neither `instar`
+  // nor `npx` is on PATH — a documented last-resort path. The direct
+  // `git worktree add` there is intentional and bounded to that case.
+  // Spec: docs/specs/AGENT-WORKTREE-CONVENTION-SPEC.md §Sequencing.
+  'src/templates/scripts/instar-worktree-create.sh',
 ]);
 
 function lintShellFile(file, text) {

package/scripts/resolve-release-tier.mjs

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+/**
+ * resolve-release-tier — Layer 2 of the Deployment Lockdown spec.
+ *
+ * Reads `.instar/release-tier.json` (committed) and decides whether the
+ * current publish attempt is permitted by the declared release tier.
+ *
+ * Why this exists. The 2026-05-19 deployment misalignment shipped four
+ * "v1.0.x" PRs as v0.28.122–v0.28.125 patches because the workflow had no
+ * concept of "we are in a holding pattern" or "this is a major-version arc."
+ * Every PR was a patch by definition. Layer 1 made package.json the version
+ * authority; Layer 2 (this script) makes the release-tier file the publish
+ * authority. Together they let an operator declare "no deploy" in code that
+ * the workflow physically honors.
+ *
+ * Allowed tier values:
+ *   "patch" — auto-publish on every NEXT.md-bearing PR (current default).
+ *   "minor" — auto-publish only when LOCAL.minor > NPM.minor.
+ *   "major" — auto-publish only when LOCAL.major > NPM.major AND Layer 5
+ *             multi-signatures are present. Layer 5 is not yet shipped, so
+ *             this tier currently blocks until Layer 5 lands.
+ *   "hold"  — auto-publish DISABLED. Used during major-feature work, after
+ *             an incident, or whenever the operator wants to pause shipping.
+ *
+ * Missing file → defaults to "patch" (the pre-Layer-2 behavior). This keeps
+ * the script safe for older checkouts that haven't been migrated.
+ *
+ * Usage:
+ *   node scripts/resolve-release-tier.mjs <localVersion> <npmVersion>
+ *     [--config-path <path>]
+ *   → exit 0 + prints "allow" to stdout when publish is permitted
+ *   → exit 0 + prints "skip" to stdout when tier blocks (workflow should
+ *     skip cleanly, not fail the run; reason goes to stderr)
+ *   → exit 2 on bad usage / invalid tier file (workflow should fail loudly)
+ *
+ * Exported as a function for unit testing.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+
+const VALID_TIERS = ['patch', 'minor', 'major', 'hold'];
+
+/**
+ * @param {string} a semver "x.y.z"
+ * @param {string} b semver "x.y.z"
+ * @returns {"gt"|"eq"|"lt"} a compared to b
+ */
+export function compareSemver(a, b) {
+  const pa = String(a).split('.').map(Number);
+  const pb = String(b).split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    const x = pa[i] || 0;
+    const y = pb[i] || 0;
+    if (x > y) return 'gt';
+    if (x < y) return 'lt';
+  }
+  return 'eq';
+}
+
+/**
+ * Compare major / minor components only.
+ * @param {string} a
+ * @param {string} b
+ * @returns {"gt"|"eq"|"lt"}
+ */
+function compareMajorMinor(a, b, depth) {
+  const pa = String(a).split('.').map(Number);
+  const pb = String(b).split('.').map(Number);
+  for (let i = 0; i < depth; i++) {
+    const x = pa[i] || 0;
+    const y = pb[i] || 0;
+    if (x > y) return 'gt';
+    if (x < y) return 'lt';
+  }
+  return 'eq';
+}
+
+/**
+ * @typedef {{ tier: "patch"|"minor"|"major"|"hold", reason?: string, setAt?: string, setBy?: string }} TierConfig
+ * @typedef {{ decision: "allow"|"skip", reason: string, tier: string }} Resolution
+ */
+
+/**
+ * @param {unknown} raw parsed JSON
+ * @returns {TierConfig}
+ */
+export function validateTierConfig(raw) {
+  if (!raw || typeof raw !== 'object') {
+    throw new Error('release-tier.json must be a JSON object');
+  }
+  const obj = /** @type {Record<string, unknown>} */ (raw);
+  const tier = obj.tier;
+  if (typeof tier !== 'string' || !VALID_TIERS.includes(tier)) {
+    throw new Error(
+      `release-tier.json: invalid tier "${String(tier)}"; must be one of ${VALID_TIERS.join(', ')}`
+    );
+  }
+  return /** @type {TierConfig} */ (obj);
+}
+
+/**
+ * Read the release-tier config. Missing file → defaults to patch.
+ * @param {string} configPath
+ * @returns {TierConfig}
+ */
+export function readTierConfig(configPath) {
+  if (!existsSync(configPath)) {
+    return { tier: 'patch', reason: 'no .instar/release-tier.json present; defaulting to patch (pre-Layer-2 behavior)' };
+  }
+  const raw = JSON.parse(readFileSync(configPath, 'utf8'));
+  return validateTierConfig(raw);
+}
+
+/**
+ * Decide whether the current publish attempt is allowed by the declared tier.
+ * @param {TierConfig} config
+ * @param {string} localVersion package.json
+ * @param {string} npmVersion `npm view instar version`
+ * @returns {Resolution}
+ */
+export function resolveReleaseTier(config, localVersion, npmVersion) {
+  const { tier } = config;
+
+  if (tier === 'hold') {
+    return {
+      decision: 'skip',
+      tier,
+      reason: `tier=hold: auto-publish is paused${config.reason ? ` (${config.reason})` : ''}. Change .instar/release-tier.json to "patch" / "minor" / "major" to resume.`,
+    };
+  }
+
+  if (tier === 'patch') {
+    return { decision: 'allow', tier, reason: 'tier=patch: routine maintenance line' };
+  }
+
+  if (tier === 'minor') {
+    const cmp = compareMajorMinor(localVersion, npmVersion, 2);
+    if (cmp === 'gt') {
+      return { decision: 'allow', tier, reason: `tier=minor: package.json (${localVersion}) declares a minor leap over npm (${npmVersion})` };
+    }
+    return {
+      decision: 'skip',
+      tier,
+      reason: `tier=minor: package.json (${localVersion}) does not declare a minor leap over npm (${npmVersion}). Bump package.json minor or change tier to "patch".`,
+    };
+  }
+
+  if (tier === 'major') {
+    // Layer 5 multi-signature gate not yet implemented. Until it ships, the
+    // major tier blocks publishes outright. This is intentional: the spec
+    // requires both LOCAL.major > NPM.major AND signature verification before
+    // a major publish. Lacking the latter, we refuse rather than ship a
+    // major version with only single-agent authority.
+    return {
+      decision: 'skip',
+      tier,
+      reason: 'tier=major: multi-signature requirement (Layer 5) not yet implemented; major publishes are blocked until that layer lands.',
+    };
+  }
+
+  // Defensive: validateTierConfig rejects unknown tiers, but TypeScript-style
+  // exhaustiveness still wants a fallback.
+  throw new Error(`unhandled tier "${tier}"`);
+}
+
+// CLI entrypoint
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const args = process.argv.slice(2);
+  let configPath = '.instar/release-tier.json';
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--config-path') {
+      configPath = args[++i];
+    } else {
+      positional.push(args[i]);
+    }
+  }
+  const [localVersion, npmVersion] = positional;
+  if (!localVersion || !npmVersion) {
+    process.stderr.write('usage: resolve-release-tier.mjs <localVersion> <npmVersion> [--config-path <path>]\n');
+    process.exit(2);
+  }
+  try {
+    const config = readTierConfig(configPath);
+    const result = resolveReleaseTier(config, localVersion, npmVersion);
+    process.stderr.write(`${result.reason}\n`);
+    process.stdout.write(result.decision);
+  } catch (err) {
+    process.stderr.write(`resolve-release-tier: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(2);
+  }
+}

package/src/data/builtin-manifest.json

@@ -1,9 +1,9 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-19T21:07:55.340Z",
-  "instarVersion": "1.0.13",
-  "entryCount": 189,
+  "generatedAt": "2026-05-20T20:25:25.571Z",
+  "instarVersion": "1.1.1",
+  "entryCount": 190,
   "entries": {
     "hook:session-start": {
       "id": "hook:session-start",
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "5ddc7a551c4e996307288ce70f6faf60337f8571a5e8f1825added7993cd48ce",
+      "contentHash": "a5a854fd1aa35f15f48183ddf263d8a0cb2dc7f67e3c513a92b4acdc0c6d28f1",
       "since": "2025-01-01"
     },
     "hook:dangerous-command-guard": {
@@ -20,7 +20,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/dangerous-command-guard.sh",
-      "contentHash": "5ddc7a551c4e996307288ce70f6faf60337f8571a5e8f1825added7993cd48ce",
+      "contentHash": "a5a854fd1aa35f15f48183ddf263d8a0cb2dc7f67e3c513a92b4acdc0c6d28f1",
       "since": "2025-01-01"
     },
     "hook:grounding-before-messaging": {
@@ -29,7 +29,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/grounding-before-messaging.sh",
-      "contentHash": "5ddc7a551c4e996307288ce70f6faf60337f8571a5e8f1825added7993cd48ce",
+      "contentHash": "a5a854fd1aa35f15f48183ddf263d8a0cb2dc7f67e3c513a92b4acdc0c6d28f1",
       "since": "2025-01-01"
     },
     "hook:compaction-recovery": {
@@ -38,7 +38,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/compaction-recovery.sh",
-      "contentHash": "5ddc7a551c4e996307288ce70f6faf60337f8571a5e8f1825added7993cd48ce",
+      "contentHash": "a5a854fd1aa35f15f48183ddf263d8a0cb2dc7f67e3c513a92b4acdc0c6d28f1",
       "since": "2025-01-01"
     },
     "hook:external-operation-gate": {
@@ -47,7 +47,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-operation-gate.js",
-      "contentHash": "5ddc7a551c4e996307288ce70f6faf60337f8571a5e8f1825added7993cd48ce",
+      "contentHash": "a5a854fd1aa35f15f48183ddf263d8a0cb2dc7f67e3c513a92b4acdc0c6d28f1",
       "since": "2025-01-01"
     },
     "hook:deferral-detector": {
@@ -56,7 +56,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/deferral-detector.js",
-      "contentHash": "5ddc7a551c4e996307288ce70f6faf60337f8571a5e8f1825added7993cd48ce",
+      "contentHash": "a5a854fd1aa35f15f48183ddf263d8a0cb2dc7f67e3c513a92b4acdc0c6d28f1",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -65,7 +65,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "5ddc7a551c4e996307288ce70f6faf60337f8571a5e8f1825added7993cd48ce",
+      "contentHash": "a5a854fd1aa35f15f48183ddf263d8a0cb2dc7f67e3c513a92b4acdc0c6d28f1",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -74,7 +74,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "5ddc7a551c4e996307288ce70f6faf60337f8571a5e8f1825added7993cd48ce",
+      "contentHash": "a5a854fd1aa35f15f48183ddf263d8a0cb2dc7f67e3c513a92b4acdc0c6d28f1",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -83,7 +83,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "5ddc7a551c4e996307288ce70f6faf60337f8571a5e8f1825added7993cd48ce",
+      "contentHash": "a5a854fd1aa35f15f48183ddf263d8a0cb2dc7f67e3c513a92b4acdc0c6d28f1",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "5ddc7a551c4e996307288ce70f6faf60337f8571a5e8f1825added7993cd48ce",
+      "contentHash": "a5a854fd1aa35f15f48183ddf263d8a0cb2dc7f67e3c513a92b4acdc0c6d28f1",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -101,7 +101,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "5ddc7a551c4e996307288ce70f6faf60337f8571a5e8f1825added7993cd48ce",
+      "contentHash": "a5a854fd1aa35f15f48183ddf263d8a0cb2dc7f67e3c513a92b4acdc0c6d28f1",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -110,7 +110,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "5ddc7a551c4e996307288ce70f6faf60337f8571a5e8f1825added7993cd48ce",
+      "contentHash": "a5a854fd1aa35f15f48183ddf263d8a0cb2dc7f67e3c513a92b4acdc0c6d28f1",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "5ddc7a551c4e996307288ce70f6faf60337f8571a5e8f1825added7993cd48ce",
+      "contentHash": "a5a854fd1aa35f15f48183ddf263d8a0cb2dc7f67e3c513a92b4acdc0c6d28f1",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -128,7 +128,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "5ddc7a551c4e996307288ce70f6faf60337f8571a5e8f1825added7993cd48ce",
+      "contentHash": "a5a854fd1aa35f15f48183ddf263d8a0cb2dc7f67e3c513a92b4acdc0c6d28f1",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -752,7 +752,7 @@
       "type": "cli-command",
       "domain": "setup",
       "sourcePath": "src/cli.ts",
-      "contentHash": "300a4557e6ab4e7d0280493a445b10333e4b57f7ef3dea12767703e0fc001f41",
+      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
       "since": "2025-01-01"
     },
     "cli:setup": {
@@ -760,7 +760,7 @@
       "type": "cli-command",
       "domain": "setup",
       "sourcePath": "src/cli.ts",
-      "contentHash": "300a4557e6ab4e7d0280493a445b10333e4b57f7ef3dea12767703e0fc001f41",
+      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
       "since": "2025-01-01"
     },
     "cli:add": {
@@ -768,7 +768,7 @@
       "type": "cli-command",
       "domain": "setup",
       "sourcePath": "src/cli.ts",
-      "contentHash": "300a4557e6ab4e7d0280493a445b10333e4b57f7ef3dea12767703e0fc001f41",
+      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
       "since": "2025-01-01"
     },
     "cli:backup": {
@@ -776,7 +776,7 @@
       "type": "cli-command",
       "domain": "operations",
       "sourcePath": "src/cli.ts",
-      "contentHash": "300a4557e6ab4e7d0280493a445b10333e4b57f7ef3dea12767703e0fc001f41",
+      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
       "since": "2025-01-01"
     },
     "cli:git": {
@@ -784,7 +784,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "300a4557e6ab4e7d0280493a445b10333e4b57f7ef3dea12767703e0fc001f41",
+      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
       "since": "2025-01-01"
     },
     "cli:memory": {
@@ -792,7 +792,7 @@
       "type": "cli-command",
       "domain": "memory",
       "sourcePath": "src/cli.ts",
-      "contentHash": "300a4557e6ab4e7d0280493a445b10333e4b57f7ef3dea12767703e0fc001f41",
+      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
       "since": "2025-01-01"
     },
     "cli:knowledge": {
@@ -800,7 +800,7 @@
       "type": "cli-command",
       "domain": "memory",
       "sourcePath": "src/cli.ts",
-      "contentHash": "300a4557e6ab4e7d0280493a445b10333e4b57f7ef3dea12767703e0fc001f41",
+      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
       "since": "2025-01-01"
     },
     "cli:semantic": {
@@ -808,7 +808,7 @@
       "type": "cli-command",
       "domain": "memory",
       "sourcePath": "src/cli.ts",
-      "contentHash": "300a4557e6ab4e7d0280493a445b10333e4b57f7ef3dea12767703e0fc001f41",
+      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
       "since": "2025-01-01"
     },
     "cli:intent": {
@@ -816,7 +816,7 @@
       "type": "cli-command",
       "domain": "intent",
       "sourcePath": "src/cli.ts",
-      "contentHash": "300a4557e6ab4e7d0280493a445b10333e4b57f7ef3dea12767703e0fc001f41",
+      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
       "since": "2025-01-01"
     },
     "cli:feedback": {
@@ -824,7 +824,7 @@
       "type": "cli-command",
       "domain": "feedback",
       "sourcePath": "src/cli.ts",
-      "contentHash": "300a4557e6ab4e7d0280493a445b10333e4b57f7ef3dea12767703e0fc001f41",
+      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
       "since": "2025-01-01"
     },
     "cli:server": {
@@ -832,7 +832,7 @@
       "type": "cli-command",
       "domain": "server",
       "sourcePath": "src/cli.ts",
-      "contentHash": "300a4557e6ab4e7d0280493a445b10333e4b57f7ef3dea12767703e0fc001f41",
+      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
       "since": "2025-01-01"
     },
     "cli:status": {
@@ -840,7 +840,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "300a4557e6ab4e7d0280493a445b10333e4b57f7ef3dea12767703e0fc001f41",
+      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
       "since": "2025-01-01"
     },
     "cli:user": {
@@ -848,7 +848,7 @@
       "type": "cli-command",
       "domain": "users",
       "sourcePath": "src/cli.ts",
-      "contentHash": "300a4557e6ab4e7d0280493a445b10333e4b57f7ef3dea12767703e0fc001f41",
+      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
       "since": "2025-01-01"
     },
     "cli:relationship": {
@@ -856,7 +856,7 @@
       "type": "cli-command",
       "domain": "relationships",
       "sourcePath": "src/cli.ts",
-      "contentHash": "300a4557e6ab4e7d0280493a445b10333e4b57f7ef3dea12767703e0fc001f41",
+      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
       "since": "2025-01-01"
     },
     "cli:job": {
@@ -864,7 +864,7 @@
       "type": "cli-command",
       "domain": "scheduling",
       "sourcePath": "src/cli.ts",
-      "contentHash": "300a4557e6ab4e7d0280493a445b10333e4b57f7ef3dea12767703e0fc001f41",
+      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
       "since": "2025-01-01"
     },
     "cli:lifeline": {
@@ -872,7 +872,7 @@
       "type": "cli-command",
       "domain": "communication",
       "sourcePath": "src/cli.ts",
-      "contentHash": "300a4557e6ab4e7d0280493a445b10333e4b57f7ef3dea12767703e0fc001f41",
+      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
       "since": "2025-01-01"
     },
     "cli:list": {
@@ -880,7 +880,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "300a4557e6ab4e7d0280493a445b10333e4b57f7ef3dea12767703e0fc001f41",
+      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
       "since": "2025-01-01"
     },
     "cli:autostart": {
@@ -888,7 +888,7 @@
       "type": "cli-command",
       "domain": "operations",
       "sourcePath": "src/cli.ts",
-      "contentHash": "300a4557e6ab4e7d0280493a445b10333e4b57f7ef3dea12767703e0fc001f41",
+      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
       "since": "2025-01-01"
     },
     "cli:migrate": {
@@ -896,7 +896,7 @@
       "type": "cli-command",
       "domain": "updates",
       "sourcePath": "src/cli.ts",
-      "contentHash": "300a4557e6ab4e7d0280493a445b10333e4b57f7ef3dea12767703e0fc001f41",
+      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
       "since": "2025-01-01"
     },
     "cli:machines": {
@@ -904,7 +904,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "300a4557e6ab4e7d0280493a445b10333e4b57f7ef3dea12767703e0fc001f41",
+      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
       "since": "2025-01-01"
     },
     "cli:whoami": {
@@ -912,7 +912,7 @@
       "type": "cli-command",
       "domain": "identity",
       "sourcePath": "src/cli.ts",
-      "contentHash": "300a4557e6ab4e7d0280493a445b10333e4b57f7ef3dea12767703e0fc001f41",
+      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
       "since": "2025-01-01"
     },
     "cli:pair": {
@@ -920,7 +920,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "300a4557e6ab4e7d0280493a445b10333e4b57f7ef3dea12767703e0fc001f41",
+      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
       "since": "2025-01-01"
     },
     "cli:join": {
@@ -928,7 +928,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "300a4557e6ab4e7d0280493a445b10333e4b57f7ef3dea12767703e0fc001f41",
+      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
       "since": "2025-01-01"
     },
     "cli:wakeup": {
@@ -936,7 +936,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "300a4557e6ab4e7d0280493a445b10333e4b57f7ef3dea12767703e0fc001f41",
+      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
       "since": "2025-01-01"
     },
     "cli:leave": {
@@ -944,7 +944,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "300a4557e6ab4e7d0280493a445b10333e4b57f7ef3dea12767703e0fc001f41",
+      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
       "since": "2025-01-01"
     },
     "cli:doctor": {
@@ -952,7 +952,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "300a4557e6ab4e7d0280493a445b10333e4b57f7ef3dea12767703e0fc001f41",
+      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
       "since": "2025-01-01"
     },
     "cli:review": {
@@ -960,7 +960,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "300a4557e6ab4e7d0280493a445b10333e4b57f7ef3dea12767703e0fc001f41",
+      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
       "since": "2025-01-01"
     },
     "cli:nuke": {
@@ -968,7 +968,7 @@
       "type": "cli-command",
       "domain": "operations",
       "sourcePath": "src/cli.ts",
-      "contentHash": "300a4557e6ab4e7d0280493a445b10333e4b57f7ef3dea12767703e0fc001f41",
+      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
       "since": "2025-01-01"
     },
     "cli:playbook": {
@@ -976,7 +976,7 @@
       "type": "cli-command",
       "domain": "context",
       "sourcePath": "src/cli.ts",
-      "contentHash": "300a4557e6ab4e7d0280493a445b10333e4b57f7ef3dea12767703e0fc001f41",
+      "contentHash": "a20f6fdbf151bdf22fb8f134fcb8bee872148b34e1f49d1fd962fb47e7200ba1",
       "since": "2025-01-01"
     },
     "template:build-stop-hook.sh": {
@@ -1104,7 +1104,15 @@
       "type": "template",
       "domain": "operations",
       "sourcePath": "src/templates/scripts/instar-watchdog.sh",
-      "contentHash": "14ec34c724149dd3df73c6296af39d09a95a74b3d471bea971aa2894c078aed3",
+      "contentHash": "364033171d32f6458b0ebe6c757a55efd578260c3211b2bfe80c5cf56e0ce0ef",
+      "since": "2025-01-01"
+    },
+    "template:instar-worktree-create.sh": {
+      "id": "template:instar-worktree-create.sh",
+      "type": "template",
+      "domain": "operations",
+      "sourcePath": "src/templates/scripts/instar-worktree-create.sh",
+      "contentHash": "2e3f78d72a00a56a9bae9dfe0af0ecc48557e5af2cd59fc6435356784c8e6796",
       "since": "2025-01-01"
     },
     "template:serendipity-capture.sh": {
@@ -1424,7 +1432,7 @@
       "type": "subsystem",
       "domain": "server",
       "sourcePath": "src/server/AgentServer.ts",
-      "contentHash": "510f556002273a0ba882a9db9cb99a22b5d96eeb1362570d5e23e12de23bb55f",
+      "contentHash": "6e996e6ea45338ffe019e539eaa738af05d5ad9a1ca35c9d93a8ba198599f759",
       "since": "2025-01-01"
     },
     "subsystem:session-manager": {
@@ -1456,7 +1464,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "5ddc7a551c4e996307288ce70f6faf60337f8571a5e8f1825added7993cd48ce",
+      "contentHash": "a5a854fd1aa35f15f48183ddf263d8a0cb2dc7f67e3c513a92b4acdc0c6d28f1",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

package/src/scaffold/templates.ts

@@ -235,6 +235,15 @@ export function generateMemoryMd(agentName: string): string {
 
 _Patterns and conventions discovered while working on this project._
 
+- **Worktree convention.** Create worktrees for collaborator repos with
+  \`instar worktree create <branch>\` — never \`git worktree add\` directly
+  into a shared checkout, and never hardcode another agent's name into the
+  path. The CLI resolves your agent's home automatically and refuses
+  unsafe placements. Reason: the macOS sandbox can revoke filesystem
+  access mid-session to anything outside the agent home, with no
+  in-session recovery path. The agent home (\`~/.instar/agents/<agent>/\`)
+  is the one location the sandbox cannot revoke.
+
 ## Tools & Scripts
 
 _Custom scripts, jobs, and integrations that have been built._
@@ -1145,6 +1154,14 @@ instar playbook doctor     # Verify everything is healthy
 ### Self-Evolution
 
 Record what I learn. Build infrastructure, not one-offs. Grow to meet the user's needs. Every session should leave things slightly better than I found them.
+
+## Worktree Convention
+
+Create worktrees for collaborator repos with \`instar worktree create <branch>\` — it resolves your agent's home automatically. Never hardcode another agent's name or place worktrees inside the shared checkout.
+
+**Why:** the macOS sandbox can revoke filesystem access to anything outside the agent home mid-session, with no in-session recovery path. The agent home (\`~/.instar/agents/<agent>/\`) is the one location the sandbox cannot revoke. \`instar worktree create\` places the worktree at \`~/.instar/agents/<agent>/.worktrees/<slug>/\` and refuses any other destination. Spec: \`docs/specs/AGENT-WORKTREE-CONVENTION-SPEC.md\`.
+
+**Caveat — git identity env vars:** the CLI sets per-worktree \`user.name\` / \`user.email\` to \`Instar Agent (<name>)\` / \`<name>@instar.local\`. \`GIT_AUTHOR_NAME\` / \`GIT_COMMITTER_EMAIL\` in the calling environment override that local config. Agents that care about commit attribution must avoid exporting those vars.
 `;
 
   if (hasTelegram) {