instar 1.3.243 → 1.3.245

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.243",
+  "version": "1.3.245",
   "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-06-04T07:16:51.612Z",
-  "instarVersion": "1.3.243",
+  "generatedAt": "2026-06-04T18:14:33.049Z",
+  "instarVersion": "1.3.245",
   "entryCount": 198,
   "entries": {
     "hook:session-start": {
@@ -778,7 +778,7 @@
       "type": "cli-command",
       "domain": "setup",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:setup": {
@@ -786,7 +786,7 @@
       "type": "cli-command",
       "domain": "setup",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:add": {
@@ -794,7 +794,7 @@
       "type": "cli-command",
       "domain": "setup",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:backup": {
@@ -802,7 +802,7 @@
       "type": "cli-command",
       "domain": "operations",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:git": {
@@ -810,7 +810,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:memory": {
@@ -818,7 +818,7 @@
       "type": "cli-command",
       "domain": "memory",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:knowledge": {
@@ -826,7 +826,7 @@
       "type": "cli-command",
       "domain": "memory",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:semantic": {
@@ -834,7 +834,7 @@
       "type": "cli-command",
       "domain": "memory",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:intent": {
@@ -842,7 +842,7 @@
       "type": "cli-command",
       "domain": "intent",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:feedback": {
@@ -850,7 +850,7 @@
       "type": "cli-command",
       "domain": "feedback",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:server": {
@@ -858,7 +858,7 @@
       "type": "cli-command",
       "domain": "server",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:status": {
@@ -866,7 +866,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:user": {
@@ -874,7 +874,7 @@
       "type": "cli-command",
       "domain": "users",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:relationship": {
@@ -882,7 +882,7 @@
       "type": "cli-command",
       "domain": "relationships",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:job": {
@@ -890,7 +890,7 @@
       "type": "cli-command",
       "domain": "scheduling",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:lifeline": {
@@ -898,7 +898,7 @@
       "type": "cli-command",
       "domain": "communication",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:list": {
@@ -906,7 +906,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:autostart": {
@@ -914,7 +914,7 @@
       "type": "cli-command",
       "domain": "operations",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:migrate": {
@@ -922,7 +922,7 @@
       "type": "cli-command",
       "domain": "updates",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:machines": {
@@ -930,7 +930,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:whoami": {
@@ -938,7 +938,7 @@
       "type": "cli-command",
       "domain": "identity",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:pair": {
@@ -946,7 +946,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:join": {
@@ -954,7 +954,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:wakeup": {
@@ -962,7 +962,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:leave": {
@@ -970,7 +970,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:doctor": {
@@ -978,7 +978,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:review": {
@@ -986,7 +986,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:nuke": {
@@ -994,7 +994,7 @@
       "type": "cli-command",
       "domain": "operations",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:playbook": {
@@ -1002,7 +1002,7 @@
       "type": "cli-command",
       "domain": "context",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:dev-preflight": {
@@ -1010,7 +1010,7 @@
       "type": "cli-command",
       "domain": "development",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:dev-ci-failures": {
@@ -1018,7 +1018,7 @@
       "type": "cli-command",
       "domain": "development",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "cli:dev-profile-node": {
@@ -1026,7 +1026,7 @@
       "type": "cli-command",
       "domain": "development",
       "sourcePath": "src/cli.ts",
-      "contentHash": "410c6f2c325138a52996c3e2339d9b21fe7a32d90a20cc83d8754ad2d44e700f",
+      "contentHash": "cedd7aaca10839a47af5a19f09b3ce8509a978166a6e2c4994fcbaa4de0a459a",
       "since": "2025-01-01"
     },
     "template:build-stop-hook.sh": {

package/upgrades/1.3.244.md

@@ -0,0 +1,23 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+- The Telegram authorized-user check is now type-tolerant. The legacy auth path compared the incoming numeric Telegram id against the configured `authorizedUserIds` with a strict membership check, so an id written as a string in config silently failed to match and the authorized user was treated as unknown (hitting the registration gate).
+- The mini-onboarding auto-add now also compares ids loosely, so it no longer appends a duplicate when the configured list already holds the id as a string.
+
+## What to Tell Your User
+
+- **Telegram access fix**: "If your Telegram user id was ever written as text in my config, I would have wrongly treated you as a stranger and asked you to register. That comparison now ignores whether the id is stored as a number or text, so the right person is recognized either way."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Type-tolerant Telegram authorization | No action needed. Existing `authorizedUserIds` entries are honored whether they are stored as numbers or strings. |
+
+## Evidence
+
+Added a focused unit test (`telegram-auth-id-type-tolerant.test.ts`, 5 cases) covering number-configured ids, string-configured ids (the regression), mixed lists, unauthorized rejection, and the empty/open passthrough. `tsc --noEmit` is clean. CI is the authority across the full shard matrix.

package/upgrades/1.3.245.md

@@ -0,0 +1,39 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Fixed the in-session server lifecycle guard so it only blocks the current
+session's own managing server. Restarting a sibling agent server by target
+directory or agent name is now allowed from inside a session.
+
+Self-targeted server lifecycle commands are still blocked, and the error now
+points operators to the supervisor path for bouncing that agent safely.
+
+The CLI import shape remains compatible with the version-detection regression
+test, and the exported guard is documented so docs coverage stays above the core
+floor.
+
+## What to Tell Your User
+
+- **Sibling agent restarts**: "I can now bounce another agent's server during
+  mentoring or fleet maintenance without being blocked by my own session guard.
+  My own managing server is still protected, so the active conversation is not
+  stranded by accident."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Restart a sibling agent server from inside a session | Use the existing server lifecycle command with a sibling target |
+| Safer self-server failure message | Automatic when an agent targets its own managing server |
+
+## Evidence
+
+Reproduced the failing shape in a unit boundary test: a session with current
+project Codey and target Gemini now returns allow, while current project Codey
+targeting Codey still returns reject. The same targeted suite also verifies that
+a symlink pointing back to Codey is rejected after realpath normalization. The
+targeted server command test file passes with all ten tests green.

package/upgrades/side-effects/server-restart-sibling-target.md

@@ -0,0 +1,96 @@
+# Side-effects review — session-safe sibling server restarts
+
+**Scope**: `instar server start|stop|restart` now checks whether the requested
+server target is the current session's own project before blocking lifecycle
+commands from inside a session. Sibling targets are allowed. Self-targets remain
+blocked and now print an actionable supervisor command.
+
+Framework-ledger ref: `57ecfb92`.
+
+## Decision audit
+
+**Candidate A: keep the blanket block and only improve the error.**
+
+This would have preserved the original safety invariant, but it would not remove
+the operational friction that caused this task. A mentoring agent still could
+not bounce a sibling agent's server from the correct workflow.
+
+**Candidate B: make the guard target-aware and keep a supervisor hint for
+self-targets.**
+
+Chosen. It preserves the invariant that a session cannot restart its own
+managing server, while allowing maintenance of sibling agents. The supervisor
+hint covers the remaining blocked case with an explicit human/operator path.
+
+## Over-block risk
+
+Low. The guard normalizes the current project and target project through
+`realpath` when possible. Sibling directories compare different and are allowed.
+The only expected block is the current managing server, including symlink aliases
+that point back to it.
+
+One residual over-block case remains intentional: if no target is provided from
+inside a session, the command targets the current project and is blocked.
+
+## Under-block risk
+
+Low. A symlink to the current project is rejected after realpath normalization.
+If a target path does not exist yet, normalization falls back to `path.resolve`;
+that could only affect non-existing paths before the server command validates
+them. Existing self-targets are protected.
+
+## Level-of-abstraction fit
+
+The comparison lives in a pure core helper. The CLI resolves the optional agent
+name before asking the helper for a decision, then formats any rejection for the
+terminal. This keeps policy separate from command output and makes the behavior
+directly unit-testable.
+
+## Signal vs authority
+
+The helper is authority for this CLI guard only. It does not change supervisor,
+launchd, systemd, or server internals. The server lifecycle implementation still
+owns the actual start/stop/restart mechanics.
+
+## Interactions
+
+- `server start [name]`, `server stop [name]`, and `server restart [name]` now
+  resolve the agent name before applying the guard.
+- `--dir` targets are compared directly.
+- `status [name]` is unchanged except that `resolveAgentDir` is now statically
+  imported by the CLI.
+- Supervisor-managed restarts remain the documented path for the current agent.
+
+## External surfaces
+
+User-facing behavior changes only for CLI output and command allowance:
+
+- Sibling server lifecycle commands from inside a session can proceed.
+- Self server lifecycle commands still fail, with a clearer message and
+  `launchctl kickstart -k gui/$UID/ai.instar.<name>` hint.
+
+No API keys, credentials, network calls, or config migrations are involved.
+
+## Rollback cost
+
+Small. Reverting the helper, CLI call-site changes, tests, and upgrade artifacts
+restores the prior blanket in-session block.
+
+## Tests
+
+Narrow regression coverage checks:
+
+- no session id allows lifecycle commands;
+- current managing server rejects;
+- sibling target allows;
+- symlink target resolving to the current managing server rejects.
+- docs coverage documents `SessionServerGuard` in two indexed docs so the core
+  category stays at its configured floor.
+
+Local verification intentionally uses targeted tests and static gates under the
+current host load; CI remains the full matrix authority.
+
+## Conclusion
+
+This change removes the Gemini-onboarding friction without weakening the
+conversation-safety invariant that motivated the guard in the first place.

package/upgrades/side-effects/telegram-auth-id-type-tolerant.md

@@ -0,0 +1,56 @@
+# Side-Effects Review — Telegram authorizedUserIds type-tolerant comparison
+
+**Version / slug:** `telegram-auth-id-type-tolerant`
+**Date:** `2026-06-04`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+The legacy (non-shared-AuthGate) Telegram auth path used
+`authorizedUserIds.includes(userId)` where `userId` is a `number` but the config
+field, though typed `number[]`, is untyped JSON at runtime and may hold the id as
+a string. `Array.prototype.includes` uses SameValueZero (no coercion), so a
+string-configured id silently failed to match and the authorized user was treated
+as unknown. The fix compares as strings (`authorized.some(id => String(id) ===
+String(userId))`), mirroring the shared-AuthGate path which is already string-based.
+The mini-onboarding auto-add (`server.ts`) is given the same loose membership check
+so it does not append a duplicate when the list already holds the id as a string.
+
+## Decision-point inventory
+
+One decision point: `isAuthorized(userId)` returns true/false (authorized vs gated).
+The change only affects WHICH equal-by-value ids match; it does not change the
+empty-list semantics (still "accept all" on the legacy path) or any other branch.
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject?** None. The change only makes the
+comparison match MORE inputs that were always intended to match (an id equal by
+value, regardless of number-vs-string representation). No id that previously
+authorized stops authorizing: `String(n) === String(n)` holds for every number that
+`includes` would have matched. The empty/absent-list "accept all" path is untouched.
+
+## 2. Under-block
+
+**What does this still miss?** It does not change the fail-open vs fail-closed
+posture of the legacy path (empty list still accepts all — unchanged, out of scope).
+It does not touch the shared-AuthGate path (already string-based) or the Slack/
+WhatsApp/iMessage adapters (separate code, their own typing). It compares by exact
+string equality after coercion, so it intentionally does NOT treat e.g. leading-zero
+or whitespace-padded ids as equal — Telegram ids are canonical integers, so this is
+correct.
+
+## 3. Blast radius
+
+Two callsites: `TelegramAdapter.isAuthorized` (the auth gate) and the `server.ts`
+mini-onboarding auto-add. Both are Telegram-only. No schema, config-shape, or API
+change — existing configs (number ids, string ids, or mixed) all keep working, and
+configs that already worked are unaffected. Behavior strictly widens recognition to
+match the documented intent.
+
+## 4. Reversibility
+
+Fully reversible: revert the two edits. No state migration, no persisted format
+change. Config files are not rewritten by this change (the mini-onboarding still
+pushes a numeric id as before; it just no longer duplicates an existing string id).