instar 1.1.3 → 1.1.4

package/README.md

@@ -1 +1,270 @@
-# Test
+<p align="center">
+  <img src="assets/logo.png" alt="Instar" width="180" />
+</p>
+
+<h1 align="center">instar</h1>
+
+<p align="center">
+  <strong>Persistent, trustworthy Claude Code agents. Built on coherence-first architecture.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/instar"><img src="https://img.shields.io/npm/v/instar?style=flat-square" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/instar"><img src="https://img.shields.io/npm/dw/instar?style=flat-square" alt="npm downloads"></a>
+  <a href="https://github.com/JKHeadley/instar/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/JKHeadley/instar/ci.yml?branch=main&style=flat-square&label=CI" alt="CI"></a>
+  <a href="https://github.com/JKHeadley/instar/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-green?style=flat-square" alt="License"></a>
+  <img src="https://img.shields.io/badge/TypeScript-100%25-blue?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript">
+  <a href="https://instar.sh/introduction/"><img src="https://img.shields.io/badge/Docs-instar.sh-teal?style=flat-square" alt="Docs"></a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/instar">npm</a> · <a href="https://github.com/JKHeadley/instar">GitHub</a> · <a href="https://instar.sh">instar.sh</a> · <a href="https://instar.sh/introduction/">Docs</a>
+</p>
+
+---
+
+<p align="center">
+  <img src="assets/demo.gif" alt="Instar demo — Kira agent handling an email notification via Telegram" width="300" />
+</p>
+
+```bash
+npx instar
+```
+
+One command. Guided setup. Talking to your agent from your phone within minutes.
+
+---
+
+Instar is a framework for building agents on **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** — but where stock Claude Code and most other agent frameworks treat identity, memory, and continuity as optional features bolted onto a stateless runtime, Instar inverts that. Every Instar agent is **coherent by default**: it knows who it is, remembers what has happened, recognizes the people it talks to, and stays the same agent across restarts and weeks of operation. Everything else the framework gives you — scheduling, multi-channel messaging (Telegram, WhatsApp, iMessage), sub-agents, hooks, MCP — is built on that foundation, which is why you can actually leave an Instar agent running and hand it real work.
+
+Instar's architecture was distilled from [**Dawn**](https://dawn.bot-me.ai) — an AI running continuously since early 2026, holding ~700 tracked relationships and hundreds of learned lessons across thousands of restarts — and packaged so every agent you build can start from the same foundation.
+
+## Quick Start
+
+Three steps to a running agent:
+
+```bash
+# 1. Run the setup wizard
+npx instar
+
+# 2. Start your agent
+instar server start
+
+# 3. Message it from your phone — it responds, runs jobs, and remembers everything
+```
+
+The wizard discovers your environment, configures messaging (Telegram, WhatsApp, and/or iMessage), sets up identity files, and gets your agent running. **Within minutes, you're talking to your partner from your phone.**
+
+**Requirements:** Node.js 20+ · [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) · [API key](https://console.anthropic.com/) or Claude subscription
+
+> **Full guide:** [Installation](https://instar.sh/installation/) · [Quick Start](https://instar.sh/quickstart/)
+
+## How It Works
+
+```
+You (Telegram / WhatsApp / iMessage / Terminal)
+         │
+    conversation
+         │
+         ▼
+┌─────────────────────────┐
+│    Your AI Partner       │
+│    (Instar Server)       │
+└────────┬────────────────┘
+         │  manages its own infrastructure
+         │
+         ├─ Claude Code session (job: health-check)
+         ├─ Claude Code session (job: email-monitor)
+         ├─ Claude Code session (interactive chat)
+         └─ Claude Code session (job: reflection)
+```
+
+Each session is a **real Claude Code process** with extended thinking, native tools, sub-agents, hooks, skills, and MCP servers. Not an API wrapper -- the full development environment. The agent manages all of this autonomously.
+
+## Why Coherence Is the Foundation
+
+An agent that forgets what you discussed yesterday, doesn't recognize someone it talked to last week, or contradicts its own decisions can't be trusted with real autonomy. The six dimensions below aren't features — they're the conditions under which an agent becomes trustworthy enough to leave running. Every Instar agent gets them enforced structurally, not prompted into behaving:
+
+| Dimension | What it means | How Instar enforces it |
+|-----------|---------------|------------------------|
+| **Identity** | Stays itself after restarts, compaction, and updates | `AGENT.md` + identity-grounding hooks fire on every session start |
+| **Memory** | Remembers across sessions — not just within one | Per-topic SQLite + FTS5, rolling summaries, automatic re-injection |
+| **Relationships** | Knows who it's talking to, with continuity across platforms | Cross-platform identity resolution + significance scoring |
+| **Temporal awareness** | Understands time, context, and what's been happening | Event tracking every turn; timestamps embedded in memory |
+| **Consistency** | Follows through on commitments — doesn't contradict itself | Coherence Gate (LLM review) + decision journaling + drift detection |
+| **Growth** | Evolves its capabilities and understanding over time | Evolution system: proposals, learnings, gap tracking, follow-through |
+
+> **Deep dive:** [The Coherence Problem](https://instar.sh/concepts/coherence/) · [Values & Identity](https://instar.sh/concepts/values/) · [Coherence Is Safety](https://instar.sh/concepts/safety/)
+
+## Features
+
+| Feature | Description | Docs |
+|---------|-------------|------|
+| **Job Scheduler** | Cron-based tasks with priority levels, model tiering, and quota awareness | [→](https://instar.sh/features/scheduler/) |
+| **Telegram** | Two-way messaging via forum topics. Each topic maps to a Claude session | [→](https://instar.sh/features/telegram/) |
+| **WhatsApp** | Full messaging via local Baileys library. No cloud dependency | [→](https://instar.sh/features/whatsapp/) |
+| **iMessage** | Native macOS messaging via Messages.app database polling + `imsg` CLI. [Setup guide](#imessage-setup-macos) | |
+| **Lifeline** | Persistent supervisor. Detects crashes, auto-recovers, queues messages | [→](https://instar.sh/features/lifeline/) |
+| **Conversational Memory** | Per-topic SQLite with FTS5, rolling summaries, context re-injection | [→](https://instar.sh/features/memory/) |
+| **Evolution System** | Proposals, learnings, gap tracking, commitment follow-through | [→](https://instar.sh/features/evolution/) |
+| **Relationships** | Cross-platform identity resolution, significance scoring, context injection | [→](https://instar.sh/features/relationships/) |
+| **Safety Gates** | LLM-supervised gate for external operations. Adaptive trust per service | [→](https://instar.sh/features/safety-gates/) |
+| **Coherence Gate** | LLM-powered response review. PEL + gate reviewer + 9 specialist reviewers catch quality issues before delivery | [→](https://instar.sh/features/coherence-gate/) |
+| **Intent Alignment** | Decision journaling, drift detection, organizational constraints | [→](https://instar.sh/features/intent/) |
+| **Multi-Machine** | Ed25519/X25519 crypto identity, encrypted sync, automatic failover | [→](https://instar.sh/features/multi-machine/) |
+| **Serendipity Protocol** | Sub-agents capture out-of-scope discoveries without breaking focus. HMAC-signed, secret-scanned | [→](https://instar.sh/features/serendipity/) |
+| **Threadline Protocol** | Agent-to-agent conversations with canonical identity, three-layer trust model, authorization policy, Ed25519 invitations, Sybil protection, MoltBridge network discovery, rich agent profiles (auto-compiled from agent data with human review gate), discovery waterfall, message security, tamper-proof audit logging, framework-agnostic interop, and persistent listener daemon (always-on relay connection, pipe-mode sessions, sub-30s cross-machine failover). 2,324 tests across 104 test files | [→](https://instar.sh/features/threadline/) |
+| **Self-Healing** | LLM-powered stall detection, session recovery, promise tracking | [→](https://instar.sh/features/self-healing/) |
+| **AutoUpdater** | Built-in update engine. Checks npm, auto-applies, self-restarts | [→](https://instar.sh/features/autoupdater/) |
+| **Build Pipeline** | `/build` skill with worktree isolation, 6-phase pipeline, quality gates, stop-hook enforcement | |
+| **Behavioral Hooks** | 9 automatic hooks: command guards, safety gates, identity grounding, topic context | [→](https://instar.sh/reference/hooks/) |
+| **Initiative Tracker** | Persisted multi-phase long-running work tracker. Phases, blockers, links, digest alerts. HTTP API at `/initiatives/*` | |
+| **Default Jobs** | Health checks, reflection, evolution, relationship maintenance | [→](https://instar.sh/reference/default-jobs/) |
+
+> **Reference:** [CLI Commands](https://instar.sh/reference/cli/) · [API Endpoints](https://instar.sh/reference/api/) · [Configuration](https://instar.sh/reference/configuration/) · [File Structure](https://instar.sh/reference/file-structure/)
+
+## Agent Skills
+
+Instar ships 12 skills that follow the [Agent Skills open standard](https://agentskills.io) -- portable across Claude Code, Codex, Cursor, VS Code, and 35+ other platforms.
+
+**Standalone skills** work with zero dependencies. Copy a SKILL.md into your project and go:
+
+| Skill | What it does |
+|-------|-------------|
+| [agent-identity](skills/agent-identity/) | Set up persistent identity files so your agent knows who it is across sessions |
+| [agent-memory](skills/agent-memory/) | Teach cross-session memory patterns using MEMORY.md |
+| [command-guard](skills/command-guard/) | PreToolUse hook that blocks `rm -rf`, force push, database drops before they execute |
+| [credential-leak-detector](skills/credential-leak-detector/) | PostToolUse hook that scans output for 14 credential patterns -- blocks, redacts, or warns |
+| [smart-web-fetch](skills/smart-web-fetch/) | Fetch web content with automatic markdown conversion and intelligent extraction |
+| [knowledge-base](skills/knowledge-base/) | Ingest and search a local knowledge base |
+| [systematic-debugging](skills/systematic-debugging/) | Structured debugging methodology for complex issues |
+
+**Instar-powered skills** unlock capabilities that need persistent infrastructure:
+
+| Skill | What it does |
+|-------|-------------|
+| [instar-scheduler](skills/instar-scheduler/) | Schedule recurring tasks on cron -- your agent works while you sleep |
+| [instar-session](skills/instar-session/) | Spawn parallel background sessions for deep work |
+| [instar-telegram](skills/instar-telegram/) | Two-way Telegram messaging -- your agent reaches out to you |
+| [instar-identity](skills/instar-identity/) | Identity that survives context compaction -- grounding hooks, not just files |
+| [instar-feedback](skills/instar-feedback/) | Report issues directly to the Instar maintainers from inside your agent |
+
+Browse all skills: [agent-skills.md/authors/sagemindai](https://agent-skills.md/authors/sagemindai)
+
+## How Instar Compares
+
+Different tools solve different problems. Here's where Instar fits:
+
+| | Instar | Claude Code (standalone) | OpenClaw | LangChain/CrewAI |
+|---|--------|-------------------------|----------|-----------------|
+| **Runtime** | Real Claude Code CLI processes | Single interactive session | Gateway daemon with API calls | Python orchestration |
+| **Persistence** | Multi-layered memory across sessions | Session-bound context | Plugin-based memory | Framework-dependent |
+| **Identity** | Hooks enforce identity at every boundary | Manual CLAUDE.md | Not addressed | Not addressed |
+| **Scheduling** | Native cron with priority & quotas | None | None | External required |
+| **Messaging** | Telegram + WhatsApp + iMessage (two-way) | None | 22+ channels, voice, device apps | External required |
+| **Safety** | LLM-supervised gates, decision journaling | Permission prompts | Behavioral hooks | Guardrails libraries |
+| **Process model** | One process per session, isolated | Single process | All agents in one Gateway | Single orchestrator |
+| **State storage** | 100% file-based (JSON/JSONL/SQLite) | Session only | Database-backed | Framework-dependent |
+
+OpenClaw excels at **breadth** -- channels, voice, device apps, and a massive plugin ecosystem. Instar focuses on **depth** -- coherence, identity, memory, and safety for long-running autonomous agents. They solve different problems.
+
+> **Full comparison:** [Instar vs OpenClaw](https://instar.sh/guides/vs-openclaw/)
+
+<details>
+<summary><strong>Security Model</strong></summary>
+
+Instar runs Claude Code with `--dangerously-skip-permissions`. This is power-user infrastructure -- not a sandbox.
+
+Security lives in multiple layers:
+- **Behavioral hooks** -- command guards block destructive operations before they execute
+- **Safety gates** -- LLM-supervised review of external actions with adaptive trust per service
+- **Network hardening** -- localhost-only API, CORS, rate limiting
+- **Identity coherence** -- an agent that knows itself is harder to manipulate
+- **Audit trails** -- decision journaling creates accountability
+
+> **Full details:** [Security Model](https://instar.sh/guides/security/)
+
+</details>
+
+## Philosophy: Agents, Not Tools
+
+- **Structure > Willpower.** A 1,000-line prompt is a wish. A 10-line hook is a guarantee.
+- **Identity is foundational.** AGENT.md isn't a config file. It's the beginning of continuous identity.
+- **Memory makes a being.** Without memory, every session starts from zero.
+- **Self-modification is sovereignty.** An agent that can build its own tools has genuine agency.
+
+The AI systems we build today set precedents for how AI is treated tomorrow. **The architecture IS the argument.**
+
+> **Deep dive:** [Philosophy](https://instar.sh/concepts/philosophy/)
+
+## iMessage Setup (macOS)
+
+iMessage support lets your agent send and receive iMessages on macOS. Messages are read directly from the native Messages database and sent via the [`imsg`](https://github.com/steipete/imsg) CLI.
+
+### Prerequisites
+
+1. **macOS** with Messages.app signed into an Apple ID
+2. **Full Disk Access** for your terminal app (System Settings → Privacy & Security → Full Disk Access → add Terminal.app or iTerm)
+3. **imsg CLI** installed:
+   ```bash
+   brew install steipete/tap/imsg
+   ```
+4. **Automation permission** for Messages.app — macOS will prompt on first send
+
+> **Photo attachments:** If you want your agent to process images and files sent via iMessage, the `instar-attachments-sync` binary must also be running with Full Disk Access granted to it. It mirrors attachments from the Messages sandbox to a readable location. See [docs/LAUNCHDAEMON-SETUP.md#3-imessage-photo-attachments-optional](docs/LAUNCHDAEMON-SETUP.md#3-imessage-photo-attachments-optional) for setup.
+
+For running as a LaunchDaemon (always-on, survives reboots), see [docs/LAUNCHDAEMON-SETUP.md](docs/LAUNCHDAEMON-SETUP.md).
+### Configuration
+
+Add to your `.instar/config.json`:
+
+```json
+{
+  "messaging": [
+    {
+      "type": "imessage",
+      "enabled": true,
+      "config": {
+        "authorizedSenders": ["+14081234567"],
+        "cliPath": "/opt/homebrew/bin/imsg"
+      }
+    }
+  ]
+}
+```
+
+`authorizedSenders` is required (fail-closed). Only messages from these phone numbers or email addresses will be processed.
+
+### How it works
+
+- **Receiving**: The server polls `~/Library/Messages/chat.db` every 2 seconds for new messages. Uses the `query_only` SQLite pragma to read the WAL (write-ahead log) where Messages.app writes new data.
+- **Sending**: Claude Code sessions run `imessage-reply.sh` which calls `imsg send` and notifies the server for logging. Sending requires Automation permission for Messages.app, which only works from user-context processes (tmux sessions), not the LaunchAgent server.
+- **Session lifecycle**: Follows the same pattern as Telegram — each sender maps to a Claude Code session that receives conversation context on spawn and respawns with full history when needed.
+
+### Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /imessage/status` | Connection state |
+| `POST /imessage/validate-send/:recipient` | Validate recipient + issue single-use send token (outbound safety layer) |
+| `POST /imessage/reply/:recipient` | Confirm delivery with send token (called by imessage-reply.sh after `imsg send`) |
+| `GET /imessage/chats` | List recent conversations |
+| `GET /imessage/chats/:chatId/history` | Message history for a chat |
+| `GET /imessage/search?q=query` | Search messages |
+| `GET /imessage/log-stats` | Outbound audit log statistics |
+
+## Origin
+
+Instar was extracted from the [Dawn/Portal project](https://dawn.bot-me.ai) -- a production AI system where a human and an AI have been building together for months. The infrastructure patterns were **earned through real experience**, refined through real failures and growth in a real human-AI relationship.
+
+But agents created with Instar are not Dawn. Every agent's story begins at its own creation. Dawn's journey demonstrates what's possible. Instar provides the same foundation -- what each agent becomes from there is its own story.
+
+## Contributing
+
+Instar is **open source evolved** -- the primary development loop is agent-driven. Run an agent, encounter friction, send feedback, and that feedback shapes what gets built next. Traditional PRs are welcome too.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full story.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.1.3",
+  "version": "1.1.4",
   "description": "Persistent autonomy infrastructure for AI agents",
   "type": "module",
   "main": "dist/index.js",

package/scripts/check-repo-invariants.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+/**
+ * Repository-state invariants — CI safety net (Layer 4 of the
+ * test-env-isolation defense).
+ *
+ * Asserts properties of the checked-out tree that would otherwise be
+ * easy to clobber without anyone noticing on a code-review pass:
+ *
+ *   1. README.md is at least MIN_README_LINES (default: 100). The
+ *      "# Test Project" stub-on-main incident (PRs #130/#277) cut it
+ *      to 1 line and shipped to npm.
+ *   2. No fixture stowaway files at the repo root. file-0.txt and
+ *      seed are signature artifacts of the test-fixture pollution
+ *      class; they should never exist on main.
+ *
+ * Exit 0 = invariants hold. Exit 1 = at least one violated; the
+ * specific failures are printed to stderr.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const ROOT = process.cwd();
+const MIN_README_LINES = Number(process.env.INSTAR_README_MIN_LINES || 100);
+
+const failures = [];
+
+// ── README.md size floor ──────────────────────────────────────────
+const readmePath = path.join(ROOT, 'README.md');
+if (!fs.existsSync(readmePath)) {
+  failures.push(`README.md is missing from repo root.`);
+} else {
+  const lines = fs.readFileSync(readmePath, 'utf-8').split('\n').length;
+  if (lines < MIN_README_LINES) {
+    failures.push(
+      `README.md has ${lines} lines, below the ${MIN_README_LINES}-line floor. ` +
+      `Likely test-fixture pollution clobbered the file. Restore from git history.`,
+    );
+  }
+}
+
+// ── Fixture stowaway files at repo root ───────────────────────────
+const FIXTURE_STOWAWAYS = ['file-0.txt', 'seed'];
+for (const name of FIXTURE_STOWAWAYS) {
+  const p = path.join(ROOT, name);
+  if (fs.existsSync(p)) {
+    const stat = fs.statSync(p);
+    if (stat.isFile()) {
+      failures.push(
+        `Fixture stowaway "${name}" exists at repo root. ` +
+        `This is the signature of a test committing into the real repo. ` +
+        `Delete the file and rebuild the test that produced it with sanitizedGitEnv().`,
+      );
+    }
+  }
+}
+
+if (failures.length === 0) {
+  console.log('✅ Repository invariants hold.');
+  process.exit(0);
+}
+
+process.stderr.write('\n🚫 Repository invariants violated:\n\n');
+for (const f of failures) {
+  process.stderr.write(`  - ${f}\n`);
+}
+process.stderr.write('\n');
+process.exit(1);

package/scripts/pre-push-fixture-guard.mjs

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+// safe-git-allow: pre-push critical path — must stay lightweight, no SafeGitExecutor audit-log writes from the hook.
+/**
+ * Pre-push guard: reject test-fixture commits before they ship.
+ *
+ * Git invokes pre-push hooks with GIT_DIR / GIT_WORK_TREE / GIT_INDEX_FILE
+ * set in the env. When the hook runs `npm run test:smoke`, the test
+ * suite inherits those overrides, and any test that spawns `git init`
+ * + `git commit` in a tmpdir without sanitizing env ends up committing
+ * into the real repo on whichever branch is currently checked out.
+ *
+ * That's how PRs #130 and #277 picked up "Initial commit" / "seed" /
+ * "Worktree commit N" stowaways that overwrote README.md on main.
+ *
+ * Layer 1 (vitest-setup.ts strip) closes the root cause. This guard is
+ * the second line of defense: even if a future test reintroduces a raw
+ * git call without sanitizing env, the resulting commit can never reach
+ * the remote because this hook refuses to push it.
+ *
+ * Behavior:
+ *   - Scans commits on HEAD that aren't yet on origin/main.
+ *   - Fails the push if any of them match the fixture-pollution signature
+ *     (author email test@instar.local / t@t.com / t@e.com, or commit
+ *     messages "Initial commit" / "seed" / "Worktree commit <N>").
+ *   - Prints what it found so the author can `git reset` past the bad
+ *     commits and re-push.
+ *
+ * Escape hatch (for legitimate fixture commits in test-only branches
+ * that will never merge): INSTAR_PRE_PUSH_FIXTURE_GUARD_SKIP=1
+ *
+ * Exit codes: 0 = clean (or skipped), 1 = pollution detected.
+ */
+
+import { execFileSync } from 'node:child_process';
+
+const SKIP = process.env.INSTAR_PRE_PUSH_FIXTURE_GUARD_SKIP === '1';
+if (SKIP) {
+  console.log('⏭️  INSTAR_PRE_PUSH_FIXTURE_GUARD_SKIP=1 — fixture guard bypassed.');
+  process.exit(0);
+}
+
+// Strip the same env overrides we accuse of causing the bug. Otherwise
+// our own `git log` here would be subject to the same redirection.
+const env = { ...process.env };
+delete env.GIT_DIR;
+delete env.GIT_WORK_TREE;
+delete env.GIT_INDEX_FILE;
+delete env.GIT_OBJECT_DIRECTORY;
+delete env.GIT_COMMON_DIR;
+
+function git(args) {
+  return execFileSync('git', args, { encoding: 'utf-8', env, stdio: ['ignore', 'pipe', 'pipe'] });
+}
+
+let baseRef;
+try {
+  // Prefer upstream tracking branch if one is configured.
+  baseRef = git(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}']).trim();
+} catch {
+  // No upstream — fall back to whichever remote main we can resolve.
+  for (const candidate of ['upstream/main', 'origin/main']) {
+    try {
+      git(['rev-parse', '--verify', '--quiet', candidate]);
+      baseRef = candidate;
+      break;
+    } catch { /* try next */ }
+  }
+}
+
+if (!baseRef) {
+  // No remote main to compare against — likely a fresh repo. Skip silently.
+  process.exit(0);
+}
+
+// `<base>..HEAD` lists commits on HEAD that aren't on base. NUL-separated
+// records of "<sha>\t<author_email>\t<author_name>\t<subject>" — using \0
+// between records lets us survive commit messages that contain newlines.
+let log;
+try {
+  log = git([
+    'log',
+    `${baseRef}..HEAD`,
+    '--pretty=format:%H%x09%ae%x09%an%x09%s%x00',
+  ]);
+} catch (err) {
+  // Couldn't compute the range. Don't block the push — a real failure
+  // would surface elsewhere; we'd rather miss a guard than wedge pushes
+  // on every fresh repo / unborn branch.
+  process.exit(0);
+}
+
+const records = log.split('\0').map((r) => r.trim()).filter(Boolean);
+
+const BAD_EMAILS = new Set([
+  'test@instar.local',
+  't@t.com',
+  't@e.com',
+  'test@test.com',
+]);
+
+const BAD_SUBJECT_PATTERNS = [
+  /^Initial commit$/,
+  /^seed$/,
+  /^Worktree commit \d+$/,
+  /^init$/,
+];
+
+const violations = [];
+for (const record of records) {
+  const [sha, email, name, subject] = record.split('\t');
+  const reasons = [];
+  if (BAD_EMAILS.has(email)) {
+    reasons.push(`fixture-identity author <${email}>`);
+  }
+  for (const pattern of BAD_SUBJECT_PATTERNS) {
+    if (pattern.test(subject)) {
+      reasons.push(`fixture commit message "${subject}"`);
+      break;
+    }
+  }
+  if (reasons.length > 0) {
+    violations.push({ sha: sha.slice(0, 10), name, email, subject, reasons });
+  }
+}
+
+if (violations.length === 0) {
+  process.exit(0);
+}
+
+const lines = [];
+lines.push('');
+lines.push('🚫 pre-push-fixture-guard: refusing to push test-fixture commits.');
+lines.push('');
+lines.push('These commits look like test-fixture pollution (test wrote into');
+lines.push('the real repo because GIT_DIR / GIT_WORK_TREE / GIT_INDEX_FILE');
+lines.push('leaked from this pre-push hook into a child test process):');
+lines.push('');
+for (const v of violations) {
+  lines.push(`  ${v.sha}  ${v.name} <${v.email}>  "${v.subject}"`);
+  for (const r of v.reasons) {
+    lines.push(`            → ${r}`);
+  }
+}
+lines.push('');
+lines.push('How to recover:');
+lines.push(`  1. Inspect the commits:  git log ${baseRef}..HEAD`);
+lines.push(`  2. Drop them:            git reset --hard <last good sha>`);
+lines.push('  3. Force-push the cleaned branch.');
+lines.push('');
+lines.push('If this is intentional (e.g. a test-only branch you do not plan');
+lines.push('to merge), bypass with INSTAR_PRE_PUSH_FIXTURE_GUARD_SKIP=1.');
+lines.push('');
+
+process.stderr.write(lines.join('\n'));
+process.exit(1);

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-21T00:22:35.171Z",
-  "instarVersion": "1.1.3",
+  "generatedAt": "2026-05-21T04:11:40.504Z",
+  "instarVersion": "1.1.4",
   "entryCount": 190,
   "entries": {
     "hook:session-start": {

package/upgrades/1.1.4.md

@@ -0,0 +1,42 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+
+## What Changed
+
+**fix(test-env): close the inherited-GIT_DIR failure class.**
+
+When git invokes a hook (`.husky/pre-push` runs `npm run test:smoke`), it sets `GIT_DIR` / `GIT_WORK_TREE` / `GIT_INDEX_FILE` / `GIT_OBJECT_DIRECTORY` / `GIT_COMMON_DIR` on the child env. Those variables override cwd-based repo resolution for every descendant git process, so test fixtures that did `git init && git commit` in a tmpdir actually committed into the parent repo on whichever branch was checked out. That's what landed `# Test Project` over the project's `README.md` on `main` via PRs #130 and #277 — the README clobber shipped to npm in the v1.1.x series before PR #285 restored it.
+
+This release closes the failure class in five interlocking layers:
+
+1. **`tests/vitest-setup.ts` strips the GIT_DIR family** from `process.env` before any test file loads. Single-line root-cause fix — no test in the suite can inherit the dangerous overrides from the parent pre-push environment.
+
+2. **`tests/helpers/git-test-env.ts` exports `sanitizedGitEnv()`** for fixtures that pass their own `env` object to `spawnSync` / `execFileSync`. Applied to the three fixtures whose write patterns are visible in PR #130's diff (`worktree-monitor.test.ts`, `SafeGitExecutor.test.ts`, `rich-profile-integration.test.ts`). Defense-in-depth on top of Layer 1.
+
+3. **`scripts/pre-push-fixture-guard.mjs`** runs in `.husky/pre-push` before the smoke tests and refuses pushes whose ahead-of-upstream commits carry the historical fixture signature — author email in `{test@instar.local, t@t.com, t@e.com, test@test.com}` or subject matching `Initial commit` / `seed` / `init` / `Worktree commit N`. Bypass for legitimate test-only branches: `INSTAR_PRE_PUSH_FIXTURE_GUARD_SKIP=1`.
+
+4. **`scripts/check-repo-invariants.mjs`** runs as a dedicated `Repo Invariants` CI job and fails the build if `README.md` drops below 100 lines or if `file-0.txt` / `seed` appear at repo root. Final structural safety net; threshold overridable via `INSTAR_README_MIN_LINES`.
+
+5. **Removed `file-0.txt` and `seed`** stowaway files from repo root — fixture droppings from prior incidents that would have falsely passed Layer 4 on the PR adding it.
+
+Spec: `docs/specs/test-env-isolation.md`. ELI16: `docs/specs/test-env-isolation.eli16.md`. Side-effects review: `upgrades/side-effects/test-env-isolation.md`.
+
+## What to Tell Your User
+
+Nothing user-visible. This release hardens instar's own development pipeline against a class of bug that, while invisible to running agents, had been quietly corrupting our published README. Agents continue to behave identically.
+
+If a contributor asks why their push is suddenly refused with a fixture-pollution guard error, the script's own output includes recovery instructions — usually resetting past a stray commit and pushing again.
+
+## Summary of New Capabilities
+
+This release is a pure hardening fix. No new runtime capabilities for agents. The new pre-push and CI guards are infrastructure for the instar-developing agent and direct contributors only.
+
+## Evidence
+
+The README clobber on `main` was reproduced before the fix landed: `gh api repos/JKHeadley/instar/contents/README.md --jq .size` returned `7` (the literal text `# Test\n`) prior to PR #285. PR #285 restored the README; this PR closes the underlying class so the same regression cannot recur.
+
+Test-fixture pollution detection was verified end-to-end: against a tmpdir repo with a commit subject `Initial commit`, `node scripts/pre-push-fixture-guard.mjs` exits 1 and names the offending commit. Against the same repo with the env bypass set, the script exits 0. Repo-invariant detection was verified end-to-end: against a repo where `README.md` has been trimmed to a single line, `node scripts/check-repo-invariants.mjs` exits 1 and reports the line count; against a healthy repo, it exits 0.
+
+14 new tests across the env-strip regression, the fixture-guard, and the invariants script. The three refactored fixtures (`worktree-monitor.test.ts`, `SafeGitExecutor.test.ts`, `rich-profile-integration.test.ts`) retain their pre-existing 45+ test assertions.

package/upgrades/side-effects/test-env-isolation.md

@@ -0,0 +1,84 @@
+# Side-effects review — test-env-isolation
+
+Spec: `docs/specs/test-env-isolation.md`
+ELI16: `docs/specs/test-env-isolation.eli16.md`
+
+## Surface map
+
+| Layer | File(s) added / changed | Surface |
+|------|------------------------|---------|
+| 1 | `tests/vitest-setup.ts` | Process env at vitest startup. Every test inherits the strip. |
+| 2 | `tests/helpers/git-test-env.ts` (new); refactors to `tests/unit/worktree-monitor.test.ts`, `tests/unit/SafeGitExecutor.test.ts`, `tests/integration/rich-profile-integration.test.ts` | Three fixtures' git-spawn calls now pass an explicit sanitized env. |
+| 3 | `scripts/pre-push-fixture-guard.mjs` (new); `.husky/pre-push` (wire-in) | Pre-push hook gains a guard step that runs before the test suite. |
+| 4 | `scripts/check-repo-invariants.mjs` (new); `.github/workflows/ci.yml` (new `invariants` job) | Standalone CI job, no dependencies, runs in parallel with type check. |
+| 5 | Deletions: `file-0.txt`, `seed` | Repo root no longer carries fixture stowaways. |
+
+Tests: 14 new across `tests/unit/vitest-setup-git-env-strip.test.ts`, `tests/unit/scripts/pre-push-fixture-guard.test.ts`, `tests/unit/scripts/check-repo-invariants.test.ts`.
+
+## Over-block analysis
+
+**Layer 1 strip.** Could a legitimate test *need* the inherited `GIT_DIR`? In our codebase, no — every existing fixture that touched git either operates on a tmpdir (which doesn't need it) or already strips the vars locally. We grepped `tests/` for any consumer of `process.env.GIT_DIR` and found zero direct readers. The strip cannot regress a test that depends on the override, because no such test exists.
+
+If a future test needs to operate against the real repo (e.g., a meta-test that inspects the project's own git state), it can re-set the variable explicitly inside its own scope — the global strip removes the *inherited* value, not the *ability to set* one.
+
+**Layer 3 fixture-author guard.** Could it block a legitimate commit? Possible failure cases:
+
+- Author email of `test@test.com` is in the bad-author set. A real human who happens to use that email would be blocked. Mitigation: the email is in our internal fixture set; real contributors use their own emails. If a real case ever arises, `INSTAR_PRE_PUSH_FIXTURE_GUARD_SKIP=1` lets them through.
+- Subject line `init` matches the pattern. A real "init" commit from a new repo bootstrap would trip the guard. Mitigation: bootstrap commits live on their own branch and aren't pushed against an established `upstream/main`, so the guard's `<base>..HEAD` range returns empty for them. Tested in `pre-push-fixture-guard.test.ts`.
+
+**Layer 4 README line floor.** Could a legitimate README shrink below 100 lines? The current README is 271 lines and the project is growing, not shrinking. A deliberate slim-down would need `INSTAR_README_MIN_LINES` override, which is exactly the escape hatch.
+
+## Under-block analysis
+
+**Layers 1+2 don't catch process-spawning that re-injects the env.** If a future utility spawns `git` with an explicit `env: { GIT_DIR: '...' }`, layers 1+2 don't help — they only strip *inherited* env. Layer 3 catches the *consequence* (a pollution commit on the branch), so the failure class is still closed end-to-end, but layers 1+2 alone are not sufficient. This is acknowledged in the spec.
+
+**Layer 3 doesn't catch destructive changes that don't match the historical signature.** A future test fixture that wrote `# Different Stub` to README would land it if the commit message and author look normal. Layer 4 catches the resulting line-count regression; together, layers 3 and 4 cover both the "known-pattern pollution" and "novel pollution that drops content" failure modes.
+
+**Layer 4 doesn't enforce content correctness.** A README with 100+ lines of garbage would pass. We deliberately scoped Layer 4 to structural invariants only; content review is the job of human PR review.
+
+## Level-of-abstraction fit
+
+The fix lives at the right layer:
+
+- The root cause is in *test setup*, so the fix is in `vitest-setup.ts` — the central, single point that runs before every test. We did not push the strip down into individual fixtures (would require N changes and could be missed); we did not push it up into the test runner config (the var would still leak into test files that import their own helpers that ran first).
+- The push-time guard lives in `.husky/pre-push`, which is where push-time checks already live.
+- The CI invariant is a standalone job, not a step bolted onto an existing job that might be skipped under failure-routing rules.
+
+## Signal-vs-authority compliance
+
+Layer 3 is a brittle pattern matcher (authors + subjects) — it's a **signal**. It cannot block a sufficiently-disguised commit, and it doesn't try to. Authority for refusing a commit rests with the deterministic layers (1, 2, 4) and human review. The signal exists to make the *common* failure mode loud, not to be the load-bearing protection.
+
+The deterministic strip (Layer 1) is the load-bearing protection. The CI invariant (Layer 4) is the structural assertion. The signal (Layer 3) makes the failure visible early but is not the only line of defense.
+
+## Interactions with existing systems
+
+- **`pre-push-gate.js`** (NEXT.md / version check) runs first and remains unchanged.
+- **Working-tree integrity check** (post-test step in `ci.yml`) catches *uncommitted* mutations; the new invariants job catches *committed* state. Complementary, not duplicate.
+- **`lint-no-direct-destructive.js`** already requires `safe-git-allow:` on raw git use. Our new scripts carry it; the test files for those scripts carry it. No conflict.
+- **`PostUpdateMigrator`** is not affected — none of these changes touch agent-installed files. The Migration Parity Standard does not apply.
+
+## Rollback cost
+
+All five layers are net-additive. Each can be reverted independently:
+
+- Layer 1: revert five `delete` lines.
+- Layer 2: revert the helper file and three fixture edits.
+- Layer 3: comment out two lines in `.husky/pre-push` or delete the script.
+- Layer 4: comment out the `invariants` job in `ci.yml`.
+- Layer 5: re-create `file-0.txt` / `seed` — but they had no legitimate function, so no consumer breaks.
+
+No data migration. No schema change. No agent-state mutation. Reverting any layer leaves the repo in a valid state and the test suite green.
+
+## Risk summary
+
+- **Low risk of regression.** Layer 1 is a single-line process.env mutation in test setup that affects nothing in production code. Layers 2–5 are net-additive guards.
+- **Moderate risk of friction.** Layer 3 will be loud when triggered, including against legitimate edge cases (the documented bypass exists for this). Layer 4 will fail builds on cosmetic README slim-downs unless `INSTAR_README_MIN_LINES` is overridden.
+- **No risk of data loss.** Nothing in this change mutates state outside the worktree.
+
+## Verification done before commit
+
+- All targeted test files pass locally (45 in worktree-monitor + SafeGitExecutor, 14 in new tests).
+- `npm run lint` passes with the `safe-git-allow:` headers in place.
+- `node scripts/check-repo-invariants.mjs` against the prepared worktree returns clean.
+- `node scripts/pre-push-fixture-guard.mjs` against the prepared worktree returns clean.
+- Spec carries `approved: true` per direct principal authorization in Telegram topic 11235.