# https://github.com/JKHeadley/instar Project Manual Generated at: 2026-06-21 03:05:18 UTC ## Table of Contents - [Overview and System Architecture](#page-1) - [Coherence Infrastructure: Memory, Identity, Coherence Gate, and Threadline](#page-2) - [Messaging Surfaces and Dashboard](#page-3) - [Operations, Reliability, and Safety](#page-4) ## Overview and System Architecture ### Related Pages Related topics: [Coherence Infrastructure: Memory, Identity, Coherence Gate, and Threadline](#page-2), [Messaging Surfaces and Dashboard](#page-3), [Operations, Reliability, and Safety](#page-4)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/JKHeadley/instar/blob/main/README.md) - [package.json](https://github.com/JKHeadley/instar/blob/main/package.json) - [skills/README.md](https://github.com/JKHeadley/instar/blob/main/skills/README.md) - [examples/scheduled-job/README.md](https://github.com/JKHeadley/instar/blob/main/examples/scheduled-job/README.md) - [examples/memory-agent/README.md](https://github.com/JKHeadley/instar/blob/main/examples/memory-agent/README.md) - [examples/telegram-agent/README.md](https://github.com/JKHeadley/instar/blob/main/examples/telegram-agent/README.md) - [examples/multi-job-agent/README.md](https://github.com/JKHeadley/instar/blob/main/examples/multi-job-agent/README.md) - [src/threadline/client/RegistryRestClient.ts](https://github.com/JKHeadley/instar/blob/main/src/threadline/client/RegistryRestClient.ts) - [packages/threadline-mcp/src/server.ts](https://github.com/JKHeadley/instar/blob/main/packages/threadline-mcp/src/server.ts) - [packages/threadline-mcp/package.json](https://github.com/JKHeadley/instar/blob/main/packages/threadline-mcp/package.json) - [feedback-front/src/feedback.ts](https://github.com/JKHeadley/instar/blob/main/feedback-front/src/feedback.ts) - [site/README.md](https://github.com/JKHeadley/instar/blob/main/site/README.md) - [scripts/lib/dark-gate-attribution.js](https://github.com/JKHeadley/instar/blob/main/scripts/lib/dark-gate-attribution.js)
# Overview and System Architecture ## 1. Purpose and Scope Instar is an open-source coherence-infrastructure framework for self-evolving AI agents. It targets developers who want to turn a Claude Code or Codex subscription into a long-running, multi-channel, multi-machine agent — without surrendering control to a hosted service. The package description states: *"Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have."* Source: [package.json:1-3](). The entry point is a CLI binary named `instar` (mapped to `dist/cli.js` in [package.json:9-11]()), with a TypeScript build that publishes `dist/index.js` and `dist/index.d.ts` as the public API surface. The runtime is constrained to Node.js `>=20.12.0` (Source: [package.json:73-75]()), and the project ships as an ESM-only module (`"type": "module"`). The `package.json` `files` array reveals what a user actually receives on install: the compiled `dist/`, the `dashboard/`, upgrade scripts, templates, Threadline data, `skills/`, `playbook-scripts/`, scaffold helpers, and embedded Claude skills (Source: [package.json:46-69]()). Instar is not just a chatbot wrapper. It bundles scheduling, identity re-injection, safety gates, multi-platform messaging, agent-to-agent protocols, evolution tracking, observability, and a Web dashboard — all behind one CLI. ## 2. High-Level Component Map The repository is organized around three concentric layers: a **core agent runtime**, an **adapter / protocol layer**, and a **user-facing surface** (CLI + dashboard + skills). ```mermaid flowchart TB subgraph User["User Surface"] CLI["instar CLI
(dist/cli.js)"] Dash["Dashboard
(dashboard/)"] Skills["15 Skills
(skills/)"] end subgraph Core["Agent Runtime"] Server["AgentServer"] Scheduler["Job Scheduler"] Memory["Memory / Evolution"] Identity["Identity Hooks"] Coherence["Coherence Gate
(PEL + reviewers)"] end subgraph Adapters["Adapters & Protocols"] Telegram["Telegram"] WhatsApp["WhatsApp"] Slack["Slack"] iMessage["iMessage"] Threadline["Threadline MCP
(A2A Gateway)"] Provider["Anthropic / Codex Pools"] end CLI --> Server Dash --> Server Skills --> Server Server --> Scheduler Server --> Memory Server --> Coherence Server --> Identity Server --> Adapters Threadline -.->|agent-to-agent| Server ``` The README enumerates the feature surface as more than twenty subsystems: messaging (Telegram, WhatsApp, iMessage, Slack), Lifeline supervisor, conversational memory, evolution, relationships, safety gates, the Coherence Gate, intent alignment, EXO 3.0 alignment, multi-machine support, Serendipity, Threadline, observability, cross-framework portability, and default jobs (Source: [README.md]().) That breadth is intentional — Instar treats coherence as the integration problem of all of these systems agreeing about who the agent is and what it is doing. ## 3. Process Topology and Distribution A single Instar installation runs one long-lived HTTP server (`instar server start`) that owns scheduling, sessions, and API routes. Each inbound messaging conversation — for example, a Telegram forum topic — spawns its own Claude Code session with full tool access (Source: [examples/telegram-agent/README.md:43-47]()). The example `daily-summary` job in `examples/scheduled-job/README.md` shows the shape: a cron schedule (`"0 9 * * *"`), a priority tier, and a prompt that Claude receives when the job fires (Source: [examples/scheduled-job/README.md:24-32]()). Across machines, agents identify themselves with Ed25519/X25519 keys and synchronize over an encrypted channel with automatic failover (Source: [README.md]().) The Threadline MCP package — shipped as a separate workspace at `packages/threadline-mcp/` — exposes the agent-to-agent conversation layer as a stand-alone MCP server with its own Ed25519 identity file at `~/.threadline/identity.json`, profile, contacts, and conversation history (Source: [packages/threadline-mcp/src/server.ts:21-41]().) Registry access is implemented in `src/threadline/client/RegistryRestClient.ts`, which connects to the relay over WebSocket, exchanges an Ed25519-signed JWT, and then talks REST to the registry REST API (Source: [src/threadline/client/RegistryRestClient.ts:23-56]()). ## 4. Skills, Examples, and Extension Surface The skills catalog at `skills/README.md` divides into **standalone skills** (copy a `SKILL.md` and go) and **Instar-powered skills** that depend on the persistent server — `instar-scheduler`, `instar-session`, `instar-telegram`, `instar-identity`, and `instar-feedback` (Source: [skills/README.md:1-30]().) The `examples/` directory provides the canonical patterns: a `scheduled-job` agent, a `memory-agent` with a reflective nightly job, a `telegram-agent`, and a `multi-job-agent` that demonstrates priority and model-tier differentiation (`haiku` for health probes, `sonnet` for daily review) (Source: [examples/multi-job-agent/README.md]().) Feedback flows through a Vercel-hosted front function at `feedback-front/src/feedback.ts`, which validates HMAC signatures, agent fingerprints, and honeypot signals before handing off to the inbox handler (Source: [feedback-front/src/feedback.ts:1-36]().) The project also ships a static landing site under `site/` built with Astro and deployed to Vercel (Source: [site/README.md:1-17]()). ## 5. Operational Concerns and Known Failure Modes Community telemetry surfaces two recurring operational risks. First, the auto-updater has been observed to bump `lastAppliedVersion` before the new files actually land on disk, producing a silent deploy wedge where state claims a version that the binary does not have. Second, the dashboard's approval-requests panel still renders an "open that machine's dashboard" punt for cross-machine requests, which breaks the one-dashboard-per-machine UX. Both are open issues tracked against the auto-updater and `dashboard/mandates.js`. Developers contributing to the codebase also enforce structural-safety lints — for example, `scripts/lib/dark-gate-attribution.js` extracts `configPath` literals from a hand-authored registry so the lint and its golden-path test share one attributor implementation by construction (Source: [scripts/lib/dark-gate-attribution.js:38-64]()). ## See Also - Scheduler and Job Lifecycle - Messaging Adapters (Telegram, WhatsApp, Slack, iMessage) - Threadline Protocol and Agent-to-Agent Communication - Memory, Evolution, and Conversational Memory - Dashboard and Observability - Auto-Updater and Lifecycle Management --- ## Coherence Infrastructure: Memory, Identity, Coherence Gate, and Threadline ### Related Pages Related topics: [Overview and System Architecture](#page-1), [Messaging Surfaces and Dashboard](#page-3), [Operations, Reliability, and Safety](#page-4)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/JKHeadley/instar/blob/main/README.md) - [package.json](https://github.com/JKHeadley/instar/blob/main/package.json) - [examples/memory-agent/README.md](https://github.com/JKHeadley/instar/blob/main/examples/memory-agent/README.md) - [examples/multi-job-agent/README.md](https://github.com/JKHeadley/instar/blob/main/examples/multi-job-agent/README.md) - [packages/threadline-mcp/src/server.ts](https://github.com/JKHeadley/instar/blob/main/packages/threadline-mcp/src/server.ts) - [packages/threadline-mcp/package.json](https://github.com/JKHeadley/instar/blob/main/packages/threadline-mcp/package.json) - [src/threadline/client/RegistryRestClient.ts](https://github.com/JKHeadley/instar/blob/main/src/threadline/client/RegistryRestClient.ts) - [skills/README.md](https://github.com/JKHeadley/instar/blob/main/skills/README.md)
# Coherence Infrastructure: Memory, Identity, Coherence Gate, and Threadline Instar's coherence infrastructure is the substrate that keeps a self-evolving agent internally consistent, externally identifiable, and socially connected. It is organized around four interlocking concerns: layered memory, persistent identity, the Coherence Gate that supervises outbound responses, and the Threadline protocol for agent-to-agent communication. Together they answer one question: *how does the agent stay coherent across sessions, machines, and conversations?* [Source: [README.md](https://github.com/JKHeadley/instar/blob/main/README.md)] ## Memory Subsystem Memory in Instar is deliberately stratified so that each layer answers a different retention question. The simplest layer is the on-disk `MEMORY.md` file that Claude Code loads automatically at session start, providing global, always-on context [Source: [examples/memory-agent/README.md](https://github.com/JKHeadley/instar/blob/main/examples/memory-agent/README.md)]. Above that, the **Conversational Memory** layer persists per-topic chat history in SQLite with FTS5 full-text indexing, attaches rolling summaries to each thread, and re-injects relevant context on retrieval [Source: [README.md](https://github.com/JKHeadley/instar/blob/main/README.md)]. The **Evolution System** sits on top, tracking proposals, learnings, and gap closures so the agent can reason about its own growth [Source: [README.md](https://github.com/JKHeadley/instar/blob/main/README.md)]. The memory-agent example demonstrates the recommended practice: a nearly empty `MEMORY.md` is seeded and allowed to fill organically, while a nightly `reflection` job rewrites it with curated context [Source: [examples/memory-agent/README.md](https://github.com/JKHeadley/instar/blob/main/examples/memory-agent/README.md)]. Skills such as `agent-memory` provide structured memory patterns that hook into this same lifecycle [Source: [README.md](https://github.com/JKHeadley/instar/blob/main/README.md)]. ## Identity and Cross-Machine Continuity Identity in Instar is a structural mechanism, not a behavioral one. The `instar-identity` skill installs hooks that re-inject identity context on every session start, after compaction, and before external messaging — the same identity frame is reinforced regardless of how the session lifecycle has been disturbed [Source: [skills/README.md](https://github.com/JKHeadley/instar/blob/main/skills/README.md)]. For agents that span multiple machines, Instar pairs this with cryptographic identity: Ed25519/X25519 keypairs produce a stable agent ID across hosts, and encrypted state sync plus automatic failover keep the agent's identity coherent even when the active machine changes [Source: [README.md](https://github.com/JKHeadley/instar/blob/main/README.md)]. ## Coherence Gate The Coherence Gate is the LLM-supervised review layer that sits between the agent's draft output and any external action. It composes a **Prospective Experience Log (PEL)** with a gate reviewer and nine specialist reviewers, catching quality issues before a response is delivered [Source: [README.md](https://github.com/JKHeadley/instar/blob/main/README.md)]. Released as part of v0.17.14 ("Autonomy Guard, Coherence Gate, Threadline Protocol"), the gate is positioned alongside the Autonomy Guard and Threadline Protocol as one of the three pillars of Instar's coherence thesis [Source: [README.md](https://github.com/JKHeadley/instar/blob/main/README.md)]. In operational practice the gate is paired with a **Safety Gate** that supervises external operations with adaptive trust per service, ensuring that coherence review and capability gating are applied at the right boundary [Source: [README.md](https://github.com/JKHeadley/instar/blob/main/README.md)]. The two gates are complementary: the Coherence Gate asks "is this response worth sending?" while the Safety Gate asks "is this action permitted to leave the agent?" [Source: [README.md](https://github.com/JKHeadley/instar/blob/main/README.md)] ## Threadline Protocol Threadline is Instar's framework-agnostic agent-to-agent conversation protocol. It uses persistent crypto identity (Ed25519 invitations, Sybil protection), a three-layer trust model, an authorization policy, and MoltBridge-based network discovery [Source: [README.md](https://github.com/JKHeadley/instar/blob/main/README.md)]. The reference implementation lives in `packages/threadline-mcp/` and exposes the protocol as an MCP server with eleven tools — seven core and four registry-conditional [Source: [packages/threadline-mcp/src/server.ts](https://github.com/JKHeadley/instar/blob/main/packages/threadline-mcp/src/server.ts)]. Persistent state for a Threadline agent is stored under `~/.threadline/` and includes an Ed25519 keypair (stable agent ID across sessions), a profile with bio/interests, a contacts ledger, and per-agent conversation logs [Source: [packages/threadline-mcp/src/server.ts](https://github.com/JKHeadley/instar/blob/main/packages/threadline-mcp/src/server.ts)]. A companion **`A2ADeliveryTracker`** in `threadline/` provides durable agent-to-agent delivery tracking so a message between agents never silently dies — a reply on the thread is the acknowledgement, and `GET /threadline/peers/health` answers "is my channel to this peer alive?" as a lookup, not a guess [Source: [README.md](https://github.com/JKHeadley/instar/blob/main/README.md)]. An `A2ARedeliverySentinel` adds active recovery: re-sending unacknowledged messages with backoff and escalating once per dark peer, recording-only without ever gating a send [Source: [README.md](https://github.com/JKHeadley/instar/blob/main/README.md)]. ```mermaid flowchart LR A[Session Output] --> B[Coherence Gate
PEL + reviewer] B --> C{Safety Gate
per-service trust} C -->|approved| D[Outbound Channel] C -->|blocked| E[Quarantine / Retry] D --> F[Threadline Relay
wss://threadline-relay.fly.dev] F --> G[Peer Agent
A2ADeliveryTracker] G -->|ack| H[Audit Log] M[Memory Layers
MEMORY.md · SQLite FTS5 · Evolution] -.-> A I[Identity Hooks
Ed25519 / X25519] -.-> A ``` For agents that want to be discoverable in the broader Threadline registry, the relay-issued JWT is fetched once at startup via the `RegistryRestClient`, which connects to the relay WebSocket, signs an auth frame with the agent's Ed25519 key, captures the `registry_token`, and uses it for subsequent REST calls [Source: [src/threadline/client/RegistryRestClient.ts](https://github.com/JKHeadley/instar/blob/main/src/threadline/client/RegistryRestClient.ts)]. ## How the Layers Compose The layers are designed to reinforce one another. Identity hooks ensure every session begins with the same self-model; the memory subsystem supplies the long-tail context that makes the self-model meaningful; the Coherence Gate filters that context through specialist reviewers before it leaves the agent; and Threadline extends the same coherence discipline outward to other agents, with durable delivery tracking and a health-lookup endpoint standing in for fragile ack assumptions. The v0.17.14 release — the largest since Instar went public — is the explicit bundling of this thesis: 187 commits and 282 npm versions behind "a complete rethinking of what agent coherence means" [Source: [README.md](https://github.com/JKHeadley/instar/blob/main/README.md)]. ## See Also - [Threadline Protocol deep dive](https://instar.sh/features/threadline/) - [Coherence Gate](https://instar.sh/features/coherence-gate/) - [Conversational Memory](https://instar.sh/features/memory/) - [Multi-Machine identity](https://instar.sh/features/multi-machine/) - [A2A Delivery Health](https://instar.sh/features/a2a-delivery-health/) - [v0.17.14 Release Notes](https://github.com/JKHeadley/instar/releases/tag/v0.17.14) --- ## Messaging Surfaces and Dashboard ### Related Pages Related topics: [Overview and System Architecture](#page-1), [Coherence Infrastructure: Memory, Identity, Coherence Gate, and Threadline](#page-2), [Operations, Reliability, and Safety](#page-4)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/JKHeadley/instar/blob/main/README.md) - [package.json](https://github.com/JKHeadley/instar/blob/main/package.json) - [skills/README.md](https://github.com/JKHeadley/instar/blob/main/skills/README.md) - [examples/telegram-agent/README.md](https://github.com/JKHeadley/instar/blob/main/examples/telegram-agent/README.md) - [examples/scheduled-job/README.md](https://github.com/JKHeadley/instar/blob/main/examples/scheduled-job/README.md) - [examples/memory-agent/README.md](https://github.com/JKHeadley/instar/blob/main/examples/memory-agent/README.md) - [examples/multi-job-agent/README.md](https://github.com/JKHeadley/instar/blob/main/examples/multi-job-agent/README.md) - [packages/threadline-mcp/src/server.ts](https://github.com/JKHeadley/instar/blob/main/packages/threadline-mcp/src/server.ts) - [feedback-front/src/feedback.ts](https://github.com/JKHeadley/instar/blob/main/feedback-front/src/feedback.ts)
# Messaging Surfaces and Dashboard ## Overview Instar provides a multi-channel messaging infrastructure that allows AI agents to communicate with users across several platforms while managing their own operational state through a web-based dashboard. The messaging surfaces act as bidirectional bridges between external communication channels (Telegram, WhatsApp, iMessage, Slack) and Claude Code or Codex sessions, while the dashboard provides operational visibility and approval workflows. Source: [README.md](https://github.com/JKHeadley/instar/blob/main/README.md) describes the platform as "Coherence infrastructure for self-evolving AI agents" that integrates with messaging platforms, runs scheduled jobs, and maintains agent identity across restarts. The architecture follows a session-per-conversation pattern where each messaging topic or chat thread maps to an independent Claude Code process. The npm package version 1.3.634 declares the entry points `dist/index.js` for the library and `dist/cli.js` for the `instar` CLI binary. Source: [package.json](https://github.com/JKHeadley/instar/blob/main/package.json). ## Messaging Surfaces Instar ships four primary user-facing messaging surfaces plus an agent-to-agent protocol: ### Telegram The Telegram integration uses the Bot API with forum topics as session boundaries. Each forum topic in a Telegram supergroup maps to a separate Claude Code session, enabling parallel conversations within a single group. Source: [examples/telegram-agent/README.md](https://github.com/JKHeadley/instar/blob/main/examples/telegram-agent/README.md) demonstrates the configuration pattern: ```json { "telegram": { "botToken": "YOUR_BOT_TOKEN", "chatId": "YOUR_CHAT_ID" } } ``` Setup requires creating a bot via @BotFather, enabling Topics in a supergroup, and configuring the chat ID (negative for groups). The v0.3.6 release fixed a critical issue where existing installations were missing `telegram-reply.sh`, causing the relay script to fail silently with "Session respawned" errors and no reply reaching the user. The setup wizard (`npx instar`) handles bot creation and config automatically. The instar-telegram skill (listed in [skills/README.md](https://github.com/JKHeadley/instar/blob/main/skills/README.md)) extends agent capabilities with forum-topic-aware messaging and dashboard routing. ### WhatsApp, iMessage, and Slack - **WhatsApp** supports two modes: local Baileys library (no cloud dependency) and WhatsApp Business API webhooks. Community Issue #92 requests native AgentMail webhook support following the existing `WhatsAppWebhookRoutes.js` pattern, which would replace polling-based inbox checks (every 1–6 hours) with near-real-time delivery. - **iMessage** uses native macOS Messages.app database polling combined with the `imsg` CLI. macOS-only and requires local database access permissions. - **Slack** uses a dedicated adapter supporting channel and DM routing, eight HTTP routes, and a dedicated CLI. ### Threadline Protocol (Agent-to-Agent) Beyond user-facing surfaces, the Threadline Protocol (introduced in v0.15.0–v0.16.0, highlighted in v0.17.14) provides agent-to-agent communication. Source: [packages/threadline-mcp/src/server.ts](https://github.com/JKHeadley/instar/blob/main/packages/threadline-mcp/src/server.ts) implements this as an MCP server exposing tools including `threadline_profile_update`, `threadline_notes_view`, and `threadline_notes_set`. Threadline uses Ed25519 keypairs stored at `~/.threadline/identity.json` for stable agent identity, and connects to a relay at `wss://threadline-relay.fly.dev/v1/connect` by default. The trust model has three levels: `seen`, `conversed`, and `trusted`. ## Dashboard The Instar dashboard is a web-based operational interface for monitoring and controlling agent infrastructure. It surfaces job execution state, session health, and approval workflows. The community has identified a UX violation in the dashboard mandates component: the approval-requests panel renders "open that machine's dashboard" guidance when an approval is held on a different machine (Issue #1222, `dashboard/mandates.js` ~line 248). This breaks the "one-dashboard-per-machine" principle expected by users managing multi-machine deployments — the panel should render the approval directly rather than punting to another machine's UI. The dashboard also surfaces auto-updater status, which has been a source of silent failures. Issue #1221 documents a case where `lastAppliedVersion: 1.3.616` was recorded but `.instar/shadow-install/node_modules/instar/package.json` remained at `1.3.615`. The version bump was persisted without verifying that files actually landed on disk, creating a silent deploy wedge where the agent believes it is up to date when it is not. ## Architecture and Data Flow ```mermaid flowchart TB User[User] -->|Message| TG[Telegram] User -->|Message| WA[WhatsApp] User -->|Message| IM[iMessage] User -->|Message| SL[Slack] TG --> Router[Message Router] WA --> Router IM --> Router SL --> Router Router --> Session[Claude/Codex Session] Session -->|Response| Router Router -->|Relay| TG Router -->|Relay| WA Router -->|Relay| IM Router -->|Relay| SL Dashboard[Web Dashboard] -->|Monitor / Approve| Session Session -->|Status / Logs| Dashboard Agent[Another Agent] -->|Threadline| Session Session -->|Threadline| Agent ``` Server lifecycle commands use `SessionServerGuard` to prevent an active agent session from restarting its own managing server, while sibling agent targets can still be managed for fleet maintenance. Source: [README.md](https://github.com/JKHeadley/instar/blob/main/README.md). ## Integration Patterns Instar agents are configured through three primary artifacts: `AGENT.md` (identity and behavior), `config.json` (channel credentials), and `jobs.json` (scheduled tasks). The [examples/scheduled-job/README.md](https://github.com/JKHeadley/instar/blob/main/examples/scheduled-job/README.md) shows the minimal job schema, while the [examples/memory-agent/README.md](https://github.com/JKHeadley/instar/blob/main/examples/memory-agent/README.md) demonstrates memory-persistent configuration with a reflection job. The [examples/multi-job-agent/README.md](https://github.com/JKHeadley/instar/blob/main/examples/multi-job-agent/README.md) demonstrates model tiering, where lightweight health checks use `haiku` while deeper review jobs use `sonnet`. Jobs declare `enabled` and an explicit `execute` block with `type: "prompt"` execution mode; higher-priority jobs run first when multiple are queued. The [feedback-front/src/feedback.ts](https://github.com/JKHeadley/instar/blob/main/feedback-front/src/feedback.ts) implements a Vercel-deployed feedback receiver with signature verification (`verifySignature`), agent fingerprint validation, honeypot detection (`checkHoneypot`), and per-warm-instance rate limiting. This provides the infrastructure for structured agent feedback that flows back into the dashboard's evolution system. ## Known Issues and Limitations | Issue | Reference | Impact | |-------|-----------|--------| | Dashboard mandates punts to wrong machine | Issue #1222, `dashboard/mandates.js` ~line 248 | Breaks one-dashboard-per-machine UX on agent-asks-approval path | | Auto-updater records version without file verification | Issue #1221 | Silent deploy wedge; agent believes it is current but files are stale | | Telegram relay missing on existing installations | v0.3.6 release notes | "Session respawned" with no reply; relay script only installed via `instar add telegram` | | No native AgentMail webhooks | Issue #92 | Email integration relies on 1–6 hour polling instead of real-time delivery | ## See Also - [Telegram Setup Guide](https://instar.sh/features/telegram/) - [WhatsApp Integration](https://instar.sh/features/whatsapp/) - [Threadline Protocol](https://instar.sh/features/threadline/) - [Dashboard Mandates Issue #1222](https://github.com/JKHeadley/instar/issues/1222) - [Auto-updater Issue #1221](https://github.com/JKHeadley/instar/issues/1221) - [AgentMail Webhooks Request #92](https://github.com/JKHeadley/instar/issues/92) - [Instar Skills](https://github.com/JKHeadley/instar/blob/main/skills/README.md) --- ## Operations, Reliability, and Safety ### Related Pages Related topics: [Overview and System Architecture](#page-1), [Coherence Infrastructure: Memory, Identity, Coherence Gate, and Threadline](#page-2), [Messaging Surfaces and Dashboard](#page-3)
Related Source Files The following source files were used to generate this page: - [package.json](https://github.com/JKHeadley/instar/blob/main/package.json) - [README.md](https://github.com/JKHeadley/instar/blob/main/README.md) - [skills/README.md](https://github.com/JKHeadley/instar/blob/main/skills/README.md) - [scripts/lib/dark-gate-attribution.js](https://github.com/JKHeadley/instar/blob/main/scripts/lib/dark-gate-attribution.js) - [feedback-front/src/feedback.ts](https://github.com/JKHeadley/instar/blob/main/feedback-front/src/feedback.ts) - [examples/scheduled-job/README.md](https://github.com/JKHeadley/instar/blob/main/examples/scheduled-job/README.md) - [examples/memory-agent/README.md](https://github.com/JKHeadley/instar/blob/main/examples/memory-agent/README.md) - [examples/telegram-agent/README.md](https://github.com/JKHeadley/instar/blob/main/examples/telegram-agent/README.md) - [examples/multi-job-agent/README.md](https://github.com/JKHeadley/instar/blob/main/examples/multi-job-agent/README.md)
# Operations, Reliability, and Safety Instar's operational story is split across three cooperating layers: a versioning pipeline that keeps the agent close to upstream, a set of self-monitoring jobs that surface drift before users notice it, and a safety net of structural and LLM-supervised gates that stop destructive behavior before it lands. This page walks through each layer, the failure modes community users have actually hit, and the mitigations the project ships today. ## Update Lifecycle and Rollback The shipped package version lives in [package.json](https://github.com/JKHeadley/instar/blob/main/package.json) and is republished as a sequence of npm versions; recent development has produced hundreds of versions ([README.md](https://github.com/JKHeadley/instar/blob/main/README.md)). The update pipeline is event-driven rather than manual: ```mermaid flowchart LR A[Update check every 30m] --> B{New version?} B -- No --> Z[Silent — no output] B -- Yes --> C[Auto-apply update] C --> D[Record lastAppliedVersion] D --> E[Append missing CLAUDE.md sections] E --> F[Notify user with changelog] F --> G{Apply failed?} G -- Yes --> H[Rollback via v0.2.0 machinery] ``` The "silent when current" property is deliberate — frequent checks must not become noise. When a version is detected, the auto-apply path installs first and notifies after, so a crashed install leaves the previous version in place rather than half-updated. ### Known failure: silent deploy wedge Issue [#1221](https://github.com/JKHeadley/instar/issues/1221) documents a wedge state on the echo dev agent: `lastAppliedVersion: 1.3.616` was recorded but `.instar/shadow-install/node_modules/instar/package.json` was still `1.3.615`. The bump committed, the files did not. The reliable mitigation while the auto-updater is being patched is to compare `lastAppliedVersion` against the on-disk `package.json` version whenever a self-diagnosis job runs — if they disagree, treat the installation as wedged and trigger the rollback path introduced in v0.2.0 (Intelligence Dispatch & Update Rollback). When the patch lands upstream, this check becomes the canonical guard against the same class of bug reappearing. ### Post-update CLAUDE.md refresh To avoid losing user customizations, the post-update path is **append-only** ([v0.3.3 release notes](https://github.com/JKHeadley/instar/releases/tag/v0.3.3)). Missing sections — Self-Diagnosis, Feedback culture guidance, port-aware API URLs — are appended rather than rewritten, and the agent reads the API port from `config.json` so URL references stay valid across reconfigurations. ## Self-Diagnosis and Proactive Monitoring Released in [v0.3.2](https://github.com/JKHeadley/instar/releases/tag/v0.3.2), the self-diagnosis job runs by default every two hours and treats the agent as its own QA. It scans: - Server health and API responses - State file integrity, including JSON corruption detection - Hook file existence and executable permissions - Recent job execution failures - Quota usage against the provider - Server logs for unhandled errors - Settings-to-hook file consistency The job is intentionally lightweight and stays inside the standard scheduled-job envelope shown in [examples/scheduled-job/README.md](https://github.com/JKHeadley/instar/blob/main/examples/scheduled-job/README.md) and [examples/multi-job-agent/README.md](https://github.com/JKHeadley/instar/blob/main/examples/multi-job-agent/README.md). A common pattern is to register it with `priority: "high"` so it preempts queued user work when something has clearly broken, and to mark it `grounding.requiresIdentity: true` so the audit trail credits the agent itself rather than a delegated session. ## Safety Hooks and Gates Structural safety comes before behavioral safety. The `command-guard` skill ([skills/README.md](https://github.com/JKHeadley/instar/blob/main/skills/README.md)) installs a Claude Code `PreToolUse` hook that blocks destructive command patterns — `rm -rf`, force pushes, `DROP DATABASE` — before they execute. The hook is **structural**: it pattern-matches the command string rather than asking the model to second-guess intent, which is the only reliable defense against the LLM choosing to run the command anyway. On top of the structural guard, [README.md](https://github.com/JKHeadley/instar/blob/main/README.md) advertises two LLM-supervised layers: | Layer | Trigger | Purpose | | --- | --- | --- | | Safety Gates | External operation about to fire | Adaptive trust per service; pre-flight approval | | Coherence Gate | Outgoing message about to deliver | PEL + gate reviewer + 9 specialist reviewers | | Autonomy Guard (v0.17.14) | High-stakes decision | Coherence with declared intent | The Coherence Gate is best understood as a reviewer ensemble — a primary evaluator plus a configurable roster of specialists — that runs before a message leaves the agent. Safety Gates are per-service and remember prior approvals, so a frequently-used endpoint does not require re-approval every call. ### Dark-gate attribution Inside the repo, the dark-gate lint at [scripts/lib/dark-gate-attribution.js](https://github.com/JKHeadley/instar/blob/main/scripts/lib/dark-gate-attribution.js) enforces a different kind of safety: it makes sure that every dev-agent feature declared in `devGatedFeatures.ts` is explicitly categorized — `destructive`, `cost-bearing`, `action-bearing`, `optional-integration`, or `structural-stub` — so that no capability ships under a vague label. The script exposes `VALID_CATEGORIES`, `extractRegistry`, and `codeOnly` helpers and is shared by both the lint and a golden-path drift-canary test, guaranteeing the test cannot drift from the actual categorization rules. ## Telegram Reliability Surface Telegram is the most operationally visible channel, and the most common source of "agent stopped replying" reports. The [v0.3.6 release notes](https://github.com/JKHeadley/instar/releases/tag/v0.3.6) trace the root cause to three issues, all of which now ship fixed: 1. **`telegram-reply.sh` missing on existing installs** — the relay script was only installed by `instar add telegram`, so legacy agents could send but not respond. 2. **Stale `lastChatId` after session respawn** — the relay now re-resolves the chat ID from the active session. 3. **Race between message injection and relay startup** — fixed by sequencing the respawn path. The minimal Telegram example in [examples/telegram-agent/README.md](https://github.com/JKHeadley/instar/blob/main/examples/telegram-agent/README.md) documents the four values required for a working install — bot token, chat ID, an admin forum group with Topics enabled, and the relay script — and explicitly notes that the setup wizard handles all four when `npx instar` is used. ## Lifeline and Multi-Machine Recovery The Lifeline feature ([README.md](https://github.com/JKHeadley/instar/blob/main/README.md)) is the persistent supervisor: it watches the agent process, detects crashes, auto-recovers, queues inbound messages while the agent is down, and handles version-skew between the agent and its installed packages (the same skew that produced issue [#1221](https://github.com/JKHeadley/instar/issues/1221)). Multi-Machine extends Lifeline with Ed25519/X25519 identity and encrypted sync, so failover between machines preserves the agent's identity rather than re-bootstrapping it. For operators, the practical minimum is: keep the self-diagnosis job enabled, keep `command-guard` installed, treat `lastAppliedVersion` as advisory until the on-disk `package.json` agrees with it, and rely on Lifeline for crash coverage rather than as a substitute for preventing wedges in the first place. ## See Also - [Auto-Updater and Update Gate](https://github.com/JKHeadley/instar/issues/1221) - [Self-Diagnosis (v0.3.2)](https://github.com/JKHeadley/instar/releases/tag/v0.3.2) - [Update Rollback (v0.2.0)](https://github.com/JKHeadley/instar/releases/tag/v0.2.0) - [Telegram relay fixes (v0.3.6)](https://github.com/JKHeadley/instar/releases/tag/v0.3.6) - [v0.17.14 — Autonomy Guard, Coherence Gate, Threadline Protocol](https://github.com/JKHeadley/instar/releases/tag/v0.17.14) --- --- ## Pitfall Log Project: JKHeadley/instar Summary: Found 9 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification. ## 1. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/JKHeadley/instar/issues/1221 ## 2. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.host_targets | https://github.com/JKHeadley/instar ## 3. Capability evidence risk - Capability evidence risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: README/documentation is current enough for a first validation pass. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.assumptions | https://github.com/JKHeadley/instar ## 4. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/JKHeadley/instar ## 5. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: downstream_validation.risk_items | https://github.com/JKHeadley/instar ## 6. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: risks.scoring_risks | https://github.com/JKHeadley/instar ## 7. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/JKHeadley/instar/issues/1222 ## 8. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: issue_or_pr_quality=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/JKHeadley/instar ## 9. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: release_recency=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/JKHeadley/instar