instar CLAUDE.md

CLAUDE.md — instar

What This Project Is

Persistent autonomy infrastructure for AI agents. Every molt, more autonomous.

Transforms Claude Code from a reactive CLI tool into a proactive, persistent agent with scheduled jobs, multi-user messaging, and system monitoring.

Born from the Dawn/Portal project — extracting battle-tested infrastructure patterns into a reusable, project-agnostic toolkit.

Quick Reference

pnpm build            # Build TypeScript
pnpm dev              # Watch mode build
pnpm test             # Unit tests
pnpm test:watch       # Watch mode tests
pnpm test:integration # Integration tests (spawns real sessions)

Architecture

src/
  core/           # SessionManager, StateManager, Config, FeedbackManager,
                  # UpdateChecker, RelationshipManager, SleepWakeDetector,
                  # SourceTreeGuard (blocks destructive managers against the instar
                  # source tree; throws SourceTreeGuardError before any mutation),
                  # SafeGitExecutor (single-funnel for all destructive git ops —
                  # execFileSync/execSync callsites replaced; enforces audit trail),
                  # SafeFsExecutor (single-funnel for all destructive fs ops —
                  # rmSync/unlinkSync/rmdirSync callsites replaced; enforces audit trail),
                  # PendingInjectStore (durable ledger of in-flight initial-message
                  # injects — queued messages survive server restarts; recorded at
                  # spawn, cleared after the inject runs, swept at boot by
                  # SessionManager.recoverPendingInjects with loud loss reporting),
                  # types
  scheduler/      # Cron-based job scheduling with quota awareness
  monitoring/     # Health checks, QuotaTracker (threshold-based load shedding),
                  # CrashLoopPauser (auto-pause runaway jobs),
                  # CompactionSentinel (verified compaction recovery lifecycle —
                  # dedupe across triggers, JSONL-growth verification, retry with
                  # backoff, zombie-kill veto while recovery is in flight),
                  # PresenceProxy (standby heartbeat — fires when a user message
                  # goes unanswered past the tier threshold),
                  # PromiseBeacon (commitment follow-through — cadenced heartbeats
                  # on open beacon-enabled commitments; atRisk non-terminal state;
                  # boot-cap enforcement via maxActiveBeacons),
                  # CommitmentTracker (commitment lifecycle + single-writer CAS
                  # mutate(); feeds PromiseBeacon and /commitments/* routes),
                  # LlmQueue (rate-limited, priority-laned LLM call queue shared
                  # across PresenceProxy and PromiseBeacon; enforces daily spend cap),
                  # SessionWatchdog (stuck-process detection + escalating kill
                  # sequence; watchdog-notifications for user-facing messages),
                  # HelperWatchdog (stall + failure detection for spawned subagents
                  # via SubagentTracker events; signal-only: emits `stall` and
                  # `helper-failed` events; consumers handle retry/messaging),
                  # DeliveryFailureSentinel (Telegram relay recovery engine — drains
                  # PendingRelayStore, deterministic state machine, fixed-template
                  # escalation after retry exhaustion; Layer 3 of delivery-robustness),
                  # TemplatesDriftVerifier (verifies deployed relay scripts against
                  # shipped instar versions via SHA-history lint; Layer 7 of
                  # delivery-robustness),
                  # TokenLedger (read-only token-usage observability — scans Claude
                  # Code JSONL transcripts, SQLite-backed, exposes /tokens/summary
                  # and /tokens/sessions; never gates or mutates source files),
                  # TokenLedgerPoller (background JSONL scanner that feeds TokenLedger;
                  # tracks byte offsets per file so re-scans are idempotent)
  messaging/      # TelegramAdapter (long-polling, JSONL history),
                  # WhatsAppAdapter, SlackAdapter, iMessage (platform adapters);
                  # TelegramMarkdownFormatter (GFM→HTML for Telegram; default
                  # 'markdown' — flip to 'legacy-passthrough' in .instar/config.json
                  # for byte-for-byte rollback; per-call `_formatMode: 'html'` opt-out
                  # for callers already producing Telegram HTML),
                  # slack/SlackMrkdwnFormatter (GFM→mrkdwn for Slack; default
                  # 'mrkdwn' — flip to 'legacy-passthrough' in the slack messaging
                  # config block for byte-for-byte rollback; per-call
                  # `formatMode: 'legacy-passthrough'` opt-out for callers already
                  # producing mrkdwn),
                  # MessageRouter (topic → adapter routing),
                  # DeliveryRetryManager (retry on failed delivery),
                  # PendingRelayStore (durable SQLite queue for Telegram relay;
                  # per-agent-id isolation; WAL + busy_timeout; Layer 2 of
                  # delivery-robustness),
                  # SpawnRequestManager (cross-session spawn coordination),
                  # MessageStore (cross-platform message persistence)
  users/          # Multi-user identity resolution and permissions
  server/         # HTTP server, routes, middleware (auth, CORS)
  scaffold/       # Identity bootstrap, template file generation
  commands/       # CLI: init, setup, server, status, user, job, add, feedback
  templates/      # Default hook scripts, helper scripts for scaffolding
tests/
  unit/           # Pure logic tests (no tmux/sessions)
  integration/    # Full system tests (may spawn real sessions)
  e2e/            # End-to-end lifecycle tests
  fixtures/       # Test data and mock repos