instar 1.0.8 → 1.0.10

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-19T19:32:42.283Z",
-  "instarVersion": "1.0.8",
+  "generatedAt": "2026-05-19T20:08:37.872Z",
+  "instarVersion": "1.0.10",
   "entryCount": 189,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "a156953ebeb92e9933387946aad8919825df0de17fba326e01ce8cb22b93c23b",
+      "contentHash": "d8ba2811113c6f6417d5555bd5490d5169dd41d5774ff5af9e171693e4d140aa",
       "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": "a156953ebeb92e9933387946aad8919825df0de17fba326e01ce8cb22b93c23b",
+      "contentHash": "d8ba2811113c6f6417d5555bd5490d5169dd41d5774ff5af9e171693e4d140aa",
       "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": "a156953ebeb92e9933387946aad8919825df0de17fba326e01ce8cb22b93c23b",
+      "contentHash": "d8ba2811113c6f6417d5555bd5490d5169dd41d5774ff5af9e171693e4d140aa",
       "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": "a156953ebeb92e9933387946aad8919825df0de17fba326e01ce8cb22b93c23b",
+      "contentHash": "d8ba2811113c6f6417d5555bd5490d5169dd41d5774ff5af9e171693e4d140aa",
       "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": "a156953ebeb92e9933387946aad8919825df0de17fba326e01ce8cb22b93c23b",
+      "contentHash": "d8ba2811113c6f6417d5555bd5490d5169dd41d5774ff5af9e171693e4d140aa",
       "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": "a156953ebeb92e9933387946aad8919825df0de17fba326e01ce8cb22b93c23b",
+      "contentHash": "d8ba2811113c6f6417d5555bd5490d5169dd41d5774ff5af9e171693e4d140aa",
       "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": "a156953ebeb92e9933387946aad8919825df0de17fba326e01ce8cb22b93c23b",
+      "contentHash": "d8ba2811113c6f6417d5555bd5490d5169dd41d5774ff5af9e171693e4d140aa",
       "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": "a156953ebeb92e9933387946aad8919825df0de17fba326e01ce8cb22b93c23b",
+      "contentHash": "d8ba2811113c6f6417d5555bd5490d5169dd41d5774ff5af9e171693e4d140aa",
       "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": "a156953ebeb92e9933387946aad8919825df0de17fba326e01ce8cb22b93c23b",
+      "contentHash": "d8ba2811113c6f6417d5555bd5490d5169dd41d5774ff5af9e171693e4d140aa",
       "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": "a156953ebeb92e9933387946aad8919825df0de17fba326e01ce8cb22b93c23b",
+      "contentHash": "d8ba2811113c6f6417d5555bd5490d5169dd41d5774ff5af9e171693e4d140aa",
       "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": "a156953ebeb92e9933387946aad8919825df0de17fba326e01ce8cb22b93c23b",
+      "contentHash": "d8ba2811113c6f6417d5555bd5490d5169dd41d5774ff5af9e171693e4d140aa",
       "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": "a156953ebeb92e9933387946aad8919825df0de17fba326e01ce8cb22b93c23b",
+      "contentHash": "d8ba2811113c6f6417d5555bd5490d5169dd41d5774ff5af9e171693e4d140aa",
       "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": "a156953ebeb92e9933387946aad8919825df0de17fba326e01ce8cb22b93c23b",
+      "contentHash": "d8ba2811113c6f6417d5555bd5490d5169dd41d5774ff5af9e171693e4d140aa",
       "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": "a156953ebeb92e9933387946aad8919825df0de17fba326e01ce8cb22b93c23b",
+      "contentHash": "d8ba2811113c6f6417d5555bd5490d5169dd41d5774ff5af9e171693e4d140aa",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1456,7 +1456,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "a156953ebeb92e9933387946aad8919825df0de17fba326e01ce8cb22b93c23b",
+      "contentHash": "d8ba2811113c6f6417d5555bd5490d5169dd41d5774ff5af9e171693e4d140aa",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

package/upgrades/1.0.10.md

@@ -0,0 +1,55 @@
+# Upgrade Guide — v1.0.10 (portability hardening 2 of 6)
+
+<!-- bump: patch -->
+
+## What Changed
+
+Second of the six cross-framework portability hardening patches (v1.0.9–v1.0.14).
+
+The Telegram reply helper script (`telegram-reply.sh`) is now also installed at
+the framework-neutral location `.instar/scripts/telegram-reply.sh`, not only
+under `.claude/scripts/`. The agent identity file's relay instructions now
+point at the neutral path (with the old Claude path documented as a fallback
+for older installs).
+
+Before this, a Codex or Gemini agent — which has no `.claude/scripts/` folder —
+was instructed by its identity file to run a relay script that did not exist,
+so it could not reply on Telegram.
+
+## Evidence
+
+Reproduction prior to this change: configure an agent to run under Codex with
+Telegram enabled. Its AGENTS.md relay section instructed `cat ... |
+.claude/scripts/telegram-reply.sh`, a path absent on a non-Claude install. The
+SessionStart hook already preferred the neutral path, but the neutral copy was
+never installed, so even that preference fell back to the missing Claude path.
+
+Observed after this change: `migrateScripts` installs the same generated script
+to `.instar/scripts/telegram-reply.sh` (install-if-missing plus the existing
+SHA-migrate guard for user-customized copies). The identity relay section now
+references the neutral path. The Claude-Code copy is retained unchanged, so
+Claude Code behavior is identical.
+
+Unit verification: `tests/unit/PostUpdateMigrator-neutralRelayPath.test.ts` —
+four cases: both locations installed with identical content; neutral copy
+executable; idempotent on re-run; no-op when Telegram is not configured. The
+IdentityRenderer assertion was updated to the neutral path plus fallback note,
+and four adjacent relay-path test files were regression-checked green.
+
+## What to Tell Your User
+
+- "Agents running on Codex or Gemini can now reply on Telegram. The reply helper is installed in a runtime-neutral location instead of a Claude-only folder. Claude Code agents are unaffected — their existing setup is unchanged and they pick up the neutral copy on their next update."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Neutral relay script location | Automatic on update. The reply helper is mirrored to `.instar/scripts/` for every runtime. |
+| Framework-neutral relay instructions | Automatic. The identity file's relay section points at the neutral path with a documented fallback. |
+
+## Deferred (Tracked Follow-ups)
+
+- Four remaining cross-framework portability gaps ship as v1.0.11–v1.0.14:
+  framework-aware connector-server registration, framework-session-store
+  abstraction, post-update-migrator framework guards, and the
+  migrator/identity-renderer unification.

package/upgrades/1.0.9.md

@@ -0,0 +1,54 @@
+# Upgrade Guide — v1.0.9 (portability hardening 1 of 6)
+
+<!-- bump: patch -->
+
+## What Changed
+
+First of the six cross-framework portability hardening patches the v1.0.8
+release notes committed to (v1.0.9–v1.0.14).
+
+`instar init` now writes the non-Claude identity files (AGENTS.md for Codex,
+GEMINI.md for Gemini) from the canonical `.instar/AGENT.md` at setup time,
+instead of writing only the Claude-Code-specific CLAUDE.md and leaving
+non-Claude runtimes with no identity file until the first server spawn.
+
+A new `renderNonClaudeIdentityShadows` helper renders every known framework
+shadow except `claude-code` (whose CLAUDE.md is a rich capability document,
+intentionally left to its own generator). It is additive, idempotent, and a
+safe no-op when no canonical identity exists yet.
+
+## Evidence
+
+Reproduction prior to this change: run `instar init` for a project intended to
+run under Codex. Result: a CLAUDE.md (which Codex does not read) and no
+AGENTS.md. The agent had no auto-loaded identity until the first server spawn
+triggered the runtime self-heal.
+
+Observed after this change: the same setup additionally produces AGENTS.md and
+GEMINI.md rendered from the canonical identity, immediately at init. CLAUDE.md
+is byte-for-byte unchanged. With no canonical AGENT.md present the helper is a
+clean no-op and does not throw.
+
+Unit verification: `tests/unit/renderNonClaudeIdentityShadows.test.ts` — five
+cases: renders AGENTS.md + GEMINI.md from canonical AGENT.md; never
+writes/clobbers CLAUDE.md; no-op-no-throw when AGENT.md is absent; idempotent;
+Telegram relay appendix on request.
+
+## What to Tell Your User
+
+- "If you set up an agent to run on Codex or Gemini, it now gets the right identity file from the moment you create it, instead of only after its first session start. Claude Code setups are unchanged."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Init-time non-Claude identity | Automatic during `instar init`. AGENTS.md / GEMINI.md are rendered from the canonical identity alongside CLAUDE.md. |
+| Idempotent re-render | The helper reproduces identical shadow content on repeat runs and no-ops without a canonical source. |
+
+## Deferred (Tracked Follow-ups)
+
+- Five remaining cross-framework portability gaps ship as v1.0.10–v1.0.14:
+  framework-aware connector-server registration, framework-session-store
+  abstraction, neutral relay-script path, post-update-migrator framework
+  guards, and the migrator/identity-renderer unification (which will revisit
+  how CLAUDE.md relates to the canonical identity render).

package/upgrades/side-effects/feat-portability-init-identity-shadows.md

@@ -0,0 +1,59 @@
+# Side-effects review — Init non-Claude identity shadows (Gap 1)
+
+Per L6. Seven dimensions.
+
+## 1. Over-block / under-block
+
+Before: UNDER — a non-Claude install got no identity file at init. After: no
+over-block. claude-code is explicitly excluded so the rich CLAUDE.md is never
+touched; only AGENTS.md/GEMINI.md are added. No new under-block: a no-canonical
+state is a clean no-op, matching prior behavior (nothing was written then
+either).
+
+## 2. Level-of-abstraction fit
+
+The render logic lives in IdentityRenderer (where all shadow rendering lives).
+init just calls it. Correct altitude — init orchestrates, the renderer renders.
+
+## 3. Signal vs Authority compliance
+
+Canonical `.instar/AGENT.md` is the AUTHORITY. The shadow files are derived
+SIGNAL copies carrying the auto-generated banner. The helper never invents
+identity; it copies the canonical body. No brittle filter gains authority.
+
+## 4. Interactions with adjacent systems
+
+- **generateClaudeMd / CLAUDE.md** — untouched (excluded by design).
+- **ensureFrameworkIdentityFile** (runtime spawn) — unchanged; this closes the
+  init-time window before first spawn, the two are complementary and both
+  idempotent so double-render is harmless.
+- **Gap 6 (migrator/renderer unification)** — independent; this PR does not
+  pre-empt or block it.
+- **PostUpdateMigrator** — not touched. Existing installs are unaffected (they
+  already self-heal at spawn via ensureFrameworkIdentityFile).
+
+## 5. Rollback cost
+
+Low. One new exported function + two call sites + one test file. `git revert`
+restores prior behavior; no state migration, deployed agents unaffected
+(runtime self-heal path unchanged).
+
+## 6. Backwards compatibility / drift surface
+
+Fully backward-compatible. Claude-code installs: identical behavior (CLAUDE.md
+written exactly as before; AGENTS.md/GEMINI.md additionally appear but are
+inert for Claude Code). Non-Claude installs: strictly better (identity present
+from init). Drift surface: none — shadows are deterministic renders of
+canonical, idempotent.
+
+## 7. Authorization / Trust posture
+
+No new authority. The helper reads canonical AGENT.md and writes derived
+shadows under projectDir — the same write surface init already owns. Best-
+effort: a render failure cannot break init or escalate anything.
+
+## Outcome
+
+Ship. Narrow, additive, verified against actual code, idempotent, fully
+tested, trivial rollback. First of the v1.0.9–v1.0.14 portability hardening
+series the v1.0.8 notes committed to.

package/upgrades/side-effects/feat-portability-neutral-relay-path.md

@@ -0,0 +1,61 @@
+# Side-effects review — Framework-neutral relay path (Gap 4)
+
+Per L6. Seven dimensions.
+
+## 1. Over-block / under-block
+
+Before: UNDER — Codex/Gemini agents instructed to run a nonexistent script.
+After: no over-block. The `.claude/scripts/` copy is retained, so Claude Code
+behavior is byte-identical. The neutral copy is additive.
+
+## 2. Level-of-abstraction fit
+
+Script installation stays in `migrateScripts` (where all reply-script
+installation lives). The identity instruction stays in IdentityRenderer. No
+logic leaked elsewhere.
+
+## 3. Signal vs Authority compliance
+
+The generated script content is the single source; both locations receive the
+same bytes. The SHA-migrate guard remains the authority on whether a
+user-customized copy is overwritten — unchanged, now applied to both copies.
+
+## 4. Interactions with adjacent systems
+
+- **SessionStart hook (3309-3314)** — already preferred the neutral path; now
+  it resolves because the file exists. No hook change needed.
+- **Claude SessionStart hook template (1822)** — intentionally unchanged
+  (Claude-only path; Codex has no SessionStart hook — that's why the appendix
+  exists).
+- **buildTelegramRelayBlock (bootstrap helper)** — separate function, not
+  touched; its tests still pass.
+- **TemplatesDriftVerifier / verify-deployed-templates** — checks
+  `.claude/scripts/telegram-reply.sh`; that file still exists with the same
+  content, so drift verification is unaffected (regression-tested).
+
+## 5. Rollback cost
+
+Low. Two source edits + one new test + one updated assertion. `git revert`
+restores prior behavior. The neutral copy left on disk after a revert is an
+inert extra file (the appendix would point back at `.claude/scripts/`),
+harmless.
+
+## 6. Backwards compatibility / drift surface
+
+Fully backward-compatible. Claude Code: unchanged. Existing agents: get the
+neutral mirror on next update via Migration Parity, idempotent. Drift surface:
+the two copies are generated from the same content in the same pass — they
+cannot diverge within a run; the SHA-migrate guard handles user customization
+identically for both.
+
+## 7. Authorization / Trust posture
+
+No new authority. Same write surface the migrator already owns
+(`.claude/scripts/` and `.instar/scripts/` are both under projectDir/stateDir
+the migrator already writes to). Best-effort: a neutral-copy write failure is
+captured as a migration error, never throws out of the migration run.
+
+## Outcome
+
+Ship. Surgical, additive, Migration-Parity-compliant, regression-swept,
+trivial rollback. Second of the v1.0.9–v1.0.14 hardening series.