instar 1.3.813 → 1.3.814

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.813",
+  "version": "1.3.814",
   "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/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-07-11T03:54:14.492Z",
-  "instarVersion": "1.3.813",
+  "generatedAt": "2026-07-11T04:35:17.292Z",
+  "instarVersion": "1.3.814",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "c56abb8d920e024e09f5d88beb426798c57ca6d55aa1221912977afa4ffdce18",
+      "contentHash": "93f638d73e5fd2f3b55f893c91ad3358c2124721ca6c7222841d3e3b67260de7",
       "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": "c56abb8d920e024e09f5d88beb426798c57ca6d55aa1221912977afa4ffdce18",
+      "contentHash": "93f638d73e5fd2f3b55f893c91ad3358c2124721ca6c7222841d3e3b67260de7",
       "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": "c56abb8d920e024e09f5d88beb426798c57ca6d55aa1221912977afa4ffdce18",
+      "contentHash": "93f638d73e5fd2f3b55f893c91ad3358c2124721ca6c7222841d3e3b67260de7",
       "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": "c56abb8d920e024e09f5d88beb426798c57ca6d55aa1221912977afa4ffdce18",
+      "contentHash": "93f638d73e5fd2f3b55f893c91ad3358c2124721ca6c7222841d3e3b67260de7",
       "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": "c56abb8d920e024e09f5d88beb426798c57ca6d55aa1221912977afa4ffdce18",
+      "contentHash": "93f638d73e5fd2f3b55f893c91ad3358c2124721ca6c7222841d3e3b67260de7",
       "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": "c56abb8d920e024e09f5d88beb426798c57ca6d55aa1221912977afa4ffdce18",
+      "contentHash": "93f638d73e5fd2f3b55f893c91ad3358c2124721ca6c7222841d3e3b67260de7",
       "since": "2025-01-01"
     },
     "hook:self-stop-guard": {
@@ -65,7 +65,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/self-stop-guard.js",
-      "contentHash": "c56abb8d920e024e09f5d88beb426798c57ca6d55aa1221912977afa4ffdce18",
+      "contentHash": "93f638d73e5fd2f3b55f893c91ad3358c2124721ca6c7222841d3e3b67260de7",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -74,7 +74,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "c56abb8d920e024e09f5d88beb426798c57ca6d55aa1221912977afa4ffdce18",
+      "contentHash": "93f638d73e5fd2f3b55f893c91ad3358c2124721ca6c7222841d3e3b67260de7",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -83,7 +83,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "c56abb8d920e024e09f5d88beb426798c57ca6d55aa1221912977afa4ffdce18",
+      "contentHash": "93f638d73e5fd2f3b55f893c91ad3358c2124721ca6c7222841d3e3b67260de7",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "c56abb8d920e024e09f5d88beb426798c57ca6d55aa1221912977afa4ffdce18",
+      "contentHash": "93f638d73e5fd2f3b55f893c91ad3358c2124721ca6c7222841d3e3b67260de7",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -101,7 +101,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "c56abb8d920e024e09f5d88beb426798c57ca6d55aa1221912977afa4ffdce18",
+      "contentHash": "93f638d73e5fd2f3b55f893c91ad3358c2124721ca6c7222841d3e3b67260de7",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -110,7 +110,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "c56abb8d920e024e09f5d88beb426798c57ca6d55aa1221912977afa4ffdce18",
+      "contentHash": "93f638d73e5fd2f3b55f893c91ad3358c2124721ca6c7222841d3e3b67260de7",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "c56abb8d920e024e09f5d88beb426798c57ca6d55aa1221912977afa4ffdce18",
+      "contentHash": "93f638d73e5fd2f3b55f893c91ad3358c2124721ca6c7222841d3e3b67260de7",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -128,7 +128,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "c56abb8d920e024e09f5d88beb426798c57ca6d55aa1221912977afa4ffdce18",
+      "contentHash": "93f638d73e5fd2f3b55f893c91ad3358c2124721ca6c7222841d3e3b67260de7",
       "since": "2025-01-01"
     },
     "hook:stop-gate-router": {
@@ -137,7 +137,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/stop-gate-router.js",
-      "contentHash": "c56abb8d920e024e09f5d88beb426798c57ca6d55aa1221912977afa4ffdce18",
+      "contentHash": "93f638d73e5fd2f3b55f893c91ad3358c2124721ca6c7222841d3e3b67260de7",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -146,7 +146,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "c56abb8d920e024e09f5d88beb426798c57ca6d55aa1221912977afa4ffdce18",
+      "contentHash": "93f638d73e5fd2f3b55f893c91ad3358c2124721ca6c7222841d3e3b67260de7",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1242,7 +1242,7 @@
       "type": "template",
       "domain": "operations",
       "sourcePath": "src/templates/scripts/telegram-reply.sh",
-      "contentHash": "89849c10aa30cc83a07d6e7721aa3ebbfd07ab897250c0d0f3e234f079dba153",
+      "contentHash": "24a638766fc8a2473e23e032dde39ff7ef046c37e893ff878323d18d9dad2d52",
       "since": "2025-01-01"
     },
     "template:whatsapp-reply.sh": {
@@ -1562,7 +1562,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "c56abb8d920e024e09f5d88beb426798c57ca6d55aa1221912977afa4ffdce18",
+      "contentHash": "93f638d73e5fd2f3b55f893c91ad3358c2124721ca6c7222841d3e3b67260de7",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

package/src/templates/scripts/telegram-reply.sh

@@ -133,7 +133,21 @@ sys.stdout.write(base64.b64decode(raw, validate=True).decode("utf-8"))
   MSG="$DECODED_MSG"
 fi
 
-# Resolve config-derived values from .instar/config.json (single python3
+# Resolve the owning agent home before reading config or recovery state.
+# Explicit launcher context wins. Otherwise, ONLY the structural .worktrees
+# marker may move us upward; a general config search could cross tenant roots
+# on a multi-agent host. The ordinary agent-home cwd remains unchanged.
+if [ -n "${INSTAR_AGENT_HOME:-}" ]; then
+  AGENT_HOME="$INSTAR_AGENT_HOME"
+else
+  case "$PWD" in
+    */.worktrees/*) AGENT_HOME="${PWD%%/.worktrees/*}" ;;
+    *) AGENT_HOME="$PWD" ;;
+  esac
+fi
+CONFIG_PATH="$AGENT_HOME/.instar/config.json"
+
+# Resolve config-derived values from the owning agent's config (single python3
 # invocation). Env > config > 4040-warn for port. Auth: INSTAR_AUTH_TOKEN env
 # first (SessionManager injects it per spawned session; survives the
 # secret-externalization refactor that moved authToken out of config.json into
@@ -143,11 +157,11 @@ fi
 AUTH_TOKEN="${INSTAR_AUTH_TOKEN:-}"
 AGENT_ID=""
 CONFIG_PORT=""
-if [ -f ".instar/config.json" ]; then
+if [ -f "$CONFIG_PATH" ]; then
   CONFIG_VALUES=$(python3 -c "
 import json, sys
 try:
-    c = json.load(open('.instar/config.json'))
+    c = json.load(open(sys.argv[1]))
 except Exception:
     sys.exit(0)
 v = c.get('authToken', '')
@@ -156,7 +170,7 @@ print(c.get('projectName', ''))
 print(c.get('port', ''))
 t = (((c.get('messaging') or {}).get('outboundAdvisory') or {}).get('timeoutMs', ''))
 print(t if isinstance(t, (int, float)) else '')
-" 2>/dev/null)
+" "$CONFIG_PATH" 2>/dev/null)
   CONFIG_AUTH=$(printf '%s\n' "$CONFIG_VALUES" | sed -n '1p')
   [ -z "$AUTH_TOKEN" ] && AUTH_TOKEN="$CONFIG_AUTH"
   AGENT_ID=$(printf '%s\n' "$CONFIG_VALUES" | sed -n '2p')
@@ -170,7 +184,7 @@ elif [ -n "$CONFIG_PORT" ]; then
   PORT="$CONFIG_PORT"
 else
   PORT=4040
-  echo "WARN: telegram-reply.sh — no INSTAR_PORT env and no port in .instar/config.json; falling back to 4040" >&2
+  echo "WARN: telegram-reply.sh — no INSTAR_PORT env and no port in $CONFIG_PATH; falling back to 4040" >&2
 fi
 
 # ── Outbound advisory preflight (inform-only; spec outbound-jargon-filepath-gap §2.4) ──
@@ -464,10 +478,15 @@ except Exception:
     # Enqueue (spec § Layer 2b). Path: <stateDir>/state/pending-relay.<agentId>.sqlite
     # Mode 0600 enforced by the Node-side store; the CLI inherits umask, so
     # we explicitly chmod after first create as well.
-    QUEUE_DIR=".instar/state"
-    mkdir -p "$QUEUE_DIR" 2>/dev/null
     # Sanitize agent-id for filename (mirrors src/messaging/pending-relay-store.ts).
     SAFE_AGENT_ID=$(printf '%s' "${AGENT_ID:-unknown}" | tr -c 'A-Za-z0-9._-' '_')
+    if [ "$SAFE_AGENT_ID" = "unknown" ]; then
+      echo "Failed (HTTP $HTTP_CODE): $BODY" >&2
+      echo "  (also: agent id is unknown; refusing to create an undrainable pending-relay.unknown.sqlite store)" >&2
+      exit 1
+    fi
+    QUEUE_DIR="$AGENT_HOME/.instar/state"
+    mkdir -p "$QUEUE_DIR" 2>/dev/null
     QUEUE_DB="${QUEUE_DIR}/pending-relay.${SAFE_AGENT_ID}.sqlite"
 
     # delivery_id — the id was minted BEFORE the initial POST and sent on it

package/upgrades/1.3.814.md

@@ -0,0 +1,24 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Telegram replies launched from inside an Instar worktree now resolve the owning agent home before reading relay configuration or writing recovery state. Recovery also refuses loudly when the agent identity is unavailable instead of creating an orphan queue that a server cannot drain.
+
+## What to Tell Your User
+
+Replies sent while development is running inside a worktree now use the same live relay configuration as the owning agent. If identity is genuinely unavailable, the send fails visibly in the session instead of leaving a hidden message that might reappear days later.
+
+## Summary of New Capabilities
+
+- Honors `INSTAR_AGENT_HOME` as the authoritative relay home.
+- Constrains automatic walk-up to the structural `/.worktrees/` marker.
+- Writes recoverable messages into the owning agent's drainable queue.
+- Refuses `pending-relay.unknown.sqlite` creation with a clear non-zero failure.
+- Re-stamps the corrected script onto existing unmodified installs during update.
+
+## Evidence
+
+Real-script integration coverage proves normal agent-home behavior, worktree resolution, explicit-home precedence, and loud unknown-id refusal. Migration tests and the shipped-template SHA ratchet prove fresh installs and existing agents receive the same corrected script.

package/upgrades/eli16/telegram-reply-worktree-home.md

@@ -0,0 +1,19 @@
+# ELI16 — Worktree replies return to the owning agent
+
+## What Changed
+
+Instar agents use a small relay script to send a conversational response back to Telegram. That script normally runs from the agent's home directory, where it can read the live server port and agent identity. During development, however, a session can run from a nested Git worktree. The old script treated that worktree as if it were a separate agent home. It could miss the real port, fail its HTTP request, and then save the reply into a database named for an `unknown` agent inside the worktree. No live server owns or drains that database, so the message becomes a ghost row that could surface much later as a duplicate.
+
+The relay now chooses its home conservatively. An explicit `INSTAR_AGENT_HOME` from the launcher wins. Without that variable, the script walks upward only when the current path contains the exact `/.worktrees/` structural marker, stopping immediately before that marker. In every ordinary directory it keeps today's behavior and uses the current directory. It never performs a broad upward search, because that could select another agent's configuration on a shared machine.
+
+## Safety Behavior
+
+Recovery still queues a transiently failed reply when the owning agent identity is known. If the identity is missing and would become `unknown`, the script prints a clear reason and exits non-zero without creating a database. The original message remains visible in the caller's transcript, making the failure recoverable and observable instead of silently stranded.
+
+## Deployment
+
+Fresh installs already source the canonical relay template. Existing agents receive the same template through PostUpdateMigrator: the v1.3.813 shipped-template hash is registered as a known safe predecessor, so an unmodified installed script is backed up and replaced during update while customized scripts retain the existing non-destructive `.new` behavior.
+
+## Evidence
+
+Integration tests execute the real Bash template against a real local HTTP server and SQLite recovery store. They cover worktree cwd resolution, explicit-home precedence, ordinary agent-home behavior, and unknown-id refusal with no orphan database. Unit tests verify migration output contains both safeguards and that historical shipped-template hashes remain complete.

package/upgrades/side-effects/telegram-reply-worktree-home.md

@@ -0,0 +1,77 @@
+# Side-Effects Review — Worktree-safe Telegram relay recovery
+
+**Version / slug:** `telegram-reply-worktree-home`
+**Date:** `2026-07-10`
+**Author:** `instar-codey`
+**Second-pass reviewer:** `framework_guard_review`
+
+## Summary of the change
+
+The canonical `telegram-reply.sh` now resolves its owning agent home from explicit `INSTAR_AGENT_HOME`, otherwise from the exact `/.worktrees/` path marker, otherwise from the unchanged current directory. Config reads and recovery queue writes use that home. Recovery refuses an `unknown` agent id loudly before creating state. PostUpdateMigrator registers the v1.3.813 template SHA so existing unmodified installs receive the fix. Integration and migration tests cover all boundaries.
+
+## Decision-point inventory
+
+- Agent-home resolution — modify — explicit launcher state wins; only a structural worktree marker permits walk-up.
+- Recoverable relay enqueue — modify — known agents retain durable enqueue; unknown identity exits non-zero without an undrainable store.
+- Existing-script migration — modify — the current shipped SHA becomes an allowed predecessor for safe backup-and-replace.
+
+## 1. Over-block
+
+A recoverable relay attempt with a genuinely missing `projectName` exits non-zero rather than queueing locally. This is intentional because a live server cannot drain an `unknown`-keyed queue. The message remains in the calling transcript and the stderr reason is explicit. Agent ids literally named `unknown` are also refused; that reserved value is already the absence fallback and cannot safely identify a drain owner.
+
+## 2. Under-block
+
+An incorrectly supplied but non-empty `INSTAR_AGENT_HOME` can still point at the wrong agent; launcher-provided identity is authoritative and this script cannot independently authenticate filesystem ownership. A cwd with a nonstandard worktree layout lacking the exact marker remains unchanged rather than guessed upward. Customized deployed relay scripts are preserved and receive a `.new` candidate, so their operator must reconcile the update through the existing degradation path.
+
+## 3. Level-of-abstraction fit
+
+The fix lives in the installed relay template because both the config lookup and recovery path are shell-side before the server can participate. It reuses the existing PostUpdateMigrator hash-safe deployment authority rather than adding another installer. The narrow structural marker is the least-powerful resolver that covers the defined worktree convention without cross-tenant discovery.
+
+## 4. Signal vs authority compliance
+
+Required reference: [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] This is hard-invariant validation at a transport boundary, not a judgment about message meaning.
+
+The unknown-id refusal has deterministic blocking authority because a queue keyed `unknown` is mechanically undrainable. It does not classify conversational content or intent. The worktree resolver likewise selects from explicit structural ownership signals and performs no semantic judgment.
+
+## 5. Interactions
+
+- **Shadowing:** home resolution runs before config-derived port/auth/id values, so all later paths share one owner. Explicit port/auth environment overrides keep their existing precedence.
+- **Double-fire:** the change prevents an orphan queue from later double-firing; known-id enqueue and delivery-failed emission retain their existing single path and delivery id.
+- **Races:** the change introduces zero shared mutable structures. The queue retains its existing SQLite concurrency and permission behavior.
+- **Feedback loops:** a refused unknown-id attempt cannot enter the redrive loop; it remains loud in the caller transcript instead.
+
+## 6. External surfaces
+
+Worktree-launched Telegram replies now reach the correct local server and recovery database. Unknown-id failures gain a clearer stderr explanation and non-zero status; they create zero persistent database files. Existing unmodified agent scripts are backed up and replaced on update. Routes, credentials, network destinations, and operator actions remain unchanged.
+
+## 6b. Operator-surface quality
+
+Operator surface unchanged; this criterion is not applicable.
+
+## 7. Multi-machine posture
+
+**Machine-local by design:** an agent home, server port, auth injection, and pending-relay database belong to the machine executing the script. The message route continues to use the local owning server, whose existing messaging layer handles user delivery. The change emits zero additional notices, creates zero cross-machine durable records, leaves topic transfer unchanged, and generates zero URLs.
+
+## 8. Rollback cost
+
+Pure script/template and migration-allowlist rollback: revert and ship a patch. Correctly queued rows remain compatible with the existing drain path. Schema and state repair are unnecessary. A rollback would reintroduce the worktree orphan risk until deployed scripts update again.
+
+## Conclusion
+
+The fix closes both halves of issue #1086 without broad filesystem discovery: worktree sessions resolve the owning agent home, and identity-less recovery fails visibly instead of persisting an undrainable ghost. Normal cwd behavior and customized-script preservation remain intact. Clear to ship after independent messaging-path review and CI.
+
+## Second-pass review
+
+**Reviewer:** framework_guard_review
+**Independent read of the artifact:** concur
+
+Home resolution is conservative and correctly ordered: explicit launcher home, exact `/.worktrees/` structural owner, then unchanged cwd. Config and recovery state share that owner; unknown identity stays transcript-visible, exits non-zero, and creates no undrainable queue. The v1.3.813 template SHA matches the migration allowlist entry, customized scripts retain the `.new` path, and the reviewer's focused suite passed 26/26.
+
+## Evidence pointers
+
+- `tests/integration/telegram-reply-end-to-end.test.ts`
+- `tests/unit/PostUpdateMigrator-telegramReply.test.ts`
+- `tests/unit/lint-template-sha-history.test.ts`
+- `tests/unit/migration-relay-script-hash.test.ts`