instar 1.0.13 → 1.1.0

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-20T16:51:39.613Z",
+  "instarVersion": "1.1.0",
+  "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": {
@@ -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) {

package/src/templates/scripts/instar-watchdog.sh

@@ -270,6 +270,7 @@ bump_fail_counter() {
 reset_fail_counter() {
   local label="$1"
   rm -f "$HEAL_STATE_DIR/$label.consecutive-heal-fails" 2>/dev/null || true
+  rm -f "$HEAL_STATE_DIR/$label.bind-fail-conflict" 2>/dev/null || true
 }
 
 # Escalate via a healthy peer agent's /attention endpoint.
@@ -289,6 +290,20 @@ escalate_via_peer() {
   # Strip ai.instar. prefix for the user-facing name
   local dead_name="${dead_label#ai.instar.}"
 
+  # If the BIND-FAIL path stashed a conflicting-project hint, use it to build
+  # a more specific summary. Falls back to the generic "offline" copy.
+  local conflict_file="$HEAL_STATE_DIR/$dead_label.bind-fail-conflict"
+  local conflict_name=""
+  if [ -r "$conflict_file" ]; then
+    conflict_name=$(cat "$conflict_file" 2>/dev/null || true)
+  fi
+  local summary_text
+  if [ -n "$conflict_name" ] && [ "$conflict_name" != "$dead_name" ]; then
+    summary_text="${dead_name} hasn't been able to start its server because ${conflict_name} is using its port. My repair attempts haven't fixed it."
+  else
+    summary_text="${dead_name} has been offline for about ${minutes_down} minutes and my repair attempts aren't working."
+  fi
+
   # Find a healthy peer
   local peer_plist peer_label peer_dir peer_port peer_auth health_code
   for peer_plist in "$LAUNCH_AGENTS_DIR"/ai.instar.*.plist; do
@@ -327,7 +342,7 @@ escalate_via_peer() {
 {
   "id": "fleet-watchdog-heal-fail-${dead_label}-${fail_count}",
   "title": "${dead_name} is offline",
-  "summary": "${dead_name} has been offline for about ${minutes_down} minutes and my repair attempts aren't working.",
+  "summary": "${summary_text}",
   "description": "Want me to dig in?",
   "category": "degradation",
   "priority": "HIGH"
@@ -389,6 +404,140 @@ JSONEOF
   return 1
 }
 
+# Probe whether an agent's lifeline-managed server actually owns its configured
+# port. Used to catch the failure mode where the lifeline (and launchd) report
+# healthy but the server itself is locked out — e.g. by a port collision with
+# another agent.
+#
+# Inputs:
+#   $1 = project_dir (e.g. /Users/x/Documents/Projects/ai-guy)
+#   $2 = label (e.g. ai.instar.ai-guy)
+#
+# Returns:
+#   0 — server reachable and identifies as the expected project (or no port
+#       configured, treat as lifeline-only and skip).
+#   2 — BIND-FAIL: port held by a different project.
+#   3 — BIND-FAIL: port unreachable while lifeline alive.
+#
+# Side-effects: writes a log line on BIND-FAIL. Stdout (single line):
+#   "<kind>\t<conflicting-project-or-empty>"  on BIND-FAIL.
+#   Empty otherwise.
+probe_server_identity() {
+  local project_dir="$1"
+  local label="$2"
+
+  [ -z "$project_dir" ] || [ ! -d "$project_dir" ] && return 0
+  local config_file="$project_dir/.instar/config.json"
+  [ ! -r "$config_file" ] && return 0
+
+  local node_bin port auth_token
+  node_bin=$(resolve_node || true)
+  [ -z "$node_bin" ] && return 0
+
+  # Read port + authToken in one node invocation. The authToken is required
+  # because /health gates the `project` field behind authentication — without
+  # it the probe can't verify identity and would silently fail-open.
+  local meta
+  meta=$("$node_bin" -e "const c=JSON.parse(require('fs').readFileSync(process.argv[1],'utf8'));process.stdout.write(String(c.port||'')+'\t'+String(c.authToken||''))" "$config_file" 2>/dev/null || true)
+  port="${meta%%	*}"
+  auth_token="${meta##*	}"
+  # Lifeline-only agents have no port; treat as healthy from probe POV.
+  [ -z "$port" ] && return 0
+
+  # Probe /health with a short timeout. Short is critical — the watchdog runs
+  # every 5 minutes and must not stall on an unresponsive server.
+  # Authorization header included so the response carries the `project` field
+  # (gated server-side; see routes.ts /health handler).
+  local resp http_code body project_field auth_args
+  auth_args=()
+  if [ -n "$auth_token" ]; then
+    auth_args=(-H "Authorization: Bearer $auth_token")
+  fi
+  resp=$(curl -sS --max-time 5 -w '\n%{http_code}' "${auth_args[@]}" "http://localhost:${port}/health" 2>/dev/null || echo $'\n000')
+  http_code=$(echo "$resp" | tail -n1)
+  body=$(echo "$resp" | sed '$d')
+
+  if [ "$http_code" != "200" ]; then
+    log "BIND-FAIL: $label — port $port unreachable while lifeline alive (http=$http_code)"
+    printf 'unreachable\t\n'
+    return 3
+  fi
+
+  # Extract the project field from the JSON response.
+  project_field=$("$node_bin" -e "try{const j=JSON.parse(require('fs').readFileSync(0,'utf8'));process.stdout.write(String(j.project||''))}catch(_){}" <<<"$body" 2>/dev/null || true)
+
+  # Derive expected name: strip ai.instar. prefix from label.
+  local expected="${label#ai.instar.}"
+
+  if [ -z "$project_field" ]; then
+    # Server is responding but doesn't expose its project — can't verify.
+    # Treat as healthy (don't false-alarm); old instar versions don't return this field.
+    return 0
+  fi
+
+  if [ "$project_field" != "$expected" ]; then
+    log "BIND-FAIL: $label — port $port owned by $project_field (expected $expected)"
+    printf 'wrong-project\t%s\n' "$project_field"
+    return 2
+  fi
+
+  return 0
+}
+
+# Run the heal + escalate pipeline for a BIND-FAIL detection. Reuses the
+# same machinery as crash-loop detection so we have ONE escalation path.
+#
+# Inputs:
+#   $1 = label
+#   $2 = project_dir
+#   $3 = plist
+#   $4 = probe stdout (kind\tconflicting-project)
+handle_bind_fail() {
+  local label="$1"
+  local project_dir="$2"
+  local plist="$3"
+  local probe_out="$4"
+  local kind conflict
+  kind="${probe_out%%	*}"
+  conflict="${probe_out#*	}"
+  conflict="${conflict%$'\n'}"
+
+  if ! should_attempt_heal "$label"; then
+    $VERBOSE && log "BIND-FAIL: $label — heal attempted recently, waiting"
+    return 0
+  fi
+
+  if try_self_heal "$project_dir" "$label"; then
+    log "RECOVERING: $label — self-heal applied for bind-fail, reloading"
+    if ! $DRY_RUN; then
+      mark_heal_attempt "$label"
+      launchctl bootout "gui/$(id -u)" "$plist" 2>/dev/null || launchctl unload "$plist" 2>/dev/null || true
+      sleep 1
+      launchctl bootstrap "gui/$(id -u)" "$plist" 2>/dev/null || launchctl load "$plist" 2>/dev/null || true
+      reset_fail_counter "$label"
+      log "RELOADED: $label (after bind-fail self-heal)"
+    else
+      log "DRY-RUN: Would reload $label after bind-fail self-heal"
+    fi
+    return 0
+  fi
+
+  # Heal can't fix it. Bump counter; escalate at threshold.
+  log "BIND-FAIL: $label — no fixable issues found ($kind${conflict:+, conflict=$conflict})"
+  mark_heal_attempt "$label"
+  local fail_count
+  fail_count=$(bump_fail_counter "$label")
+  if [ "$fail_count" -ge "$ESCALATE_AFTER_FAILS" ]; then
+    # Stash the bind-fail context so escalate_via_peer can pick it up.
+    if [ -n "$conflict" ]; then
+      echo "$conflict" > "$HEAL_STATE_DIR/$label.bind-fail-conflict"
+    fi
+    escalate_via_peer "$label" "$fail_count" || true
+  else
+    $VERBOSE && log "FAIL-COUNT: $label — ${fail_count}/${ESCALATE_AFTER_FAILS}"
+  fi
+}
+
 recovered=0
 checked=0
 for plist in "$LAUNCH_AGENTS_DIR"/ai.instar.*.plist; do
@@ -405,10 +554,21 @@ for plist in "$LAUNCH_AGENTS_DIR"/ai.instar.*.plist; do
     exit_status=$(launchctl list "$label" 2>/dev/null | grep '"LastExitStatus"' | grep -o '[0-9]*' || true)
 
     if [ -n "$pid" ] && [ "$pid" != "0" ]; then
-      # Healthy — clear heal state
-      rm -f "$HEAL_STATE_DIR/$label.last-heal" 2>/dev/null || true
-      reset_fail_counter "$label"
-      $VERBOSE && log "OK: $label (PID $pid)"
+      # Lifeline-level healthy. But the lifeline can be alive while the agent's
+      # server is locked out of its port (e.g. port collision with a peer).
+      # Run the bind-probe to catch that.
+      project_dir=$(get_project_dir "$plist")
+      probe_out=$(probe_server_identity "$project_dir" "$label")
+      probe_rc=$?
+      if [ "$probe_rc" -eq 0 ]; then
+        # Truly healthy — clear heal state
+        rm -f "$HEAL_STATE_DIR/$label.last-heal" 2>/dev/null || true
+        rm -f "$HEAL_STATE_DIR/$label.bind-fail-conflict" 2>/dev/null || true
+        reset_fail_counter "$label"
+        $VERBOSE && log "OK: $label (PID $pid)"
+      else
+        handle_bind_fail "$label" "$project_dir" "$plist" "$probe_out"
+      fi
     elif [ -n "$exit_status" ] && [ "$exit_status" != "0" ]; then
       log "CRASH-LOOP: $label (exit $exit_status, no PID)"
 
@@ -472,4 +632,7 @@ if [ -f "$LOG_FILE" ] && [ "$(wc -l < "$LOG_FILE")" -gt 1000 ]; then
 fi
 
 # Trim heal state files older than 24 hours
-find "$HEAL_STATE_DIR" -name "*.last-heal" -mmin +1440 -delete 2>/dev/null || true
+# Trim heal-state files older than 24 hours. Covers all per-label markers:
+# *.last-heal, *.consecutive-heal-fails, *.bind-fail-conflict — so state from
+# uninstalled agents doesn't accumulate indefinitely.
+find "$HEAL_STATE_DIR" \( -name "*.last-heal" -o -name "*.consecutive-heal-fails" -o -name "*.bind-fail-conflict" \) -mmin +1440 -delete 2>/dev/null || true