instar 1.3.1 → 1.3.2

package/dist/core/CodexCliIntelligenceProvider.d.ts

@@ -22,16 +22,17 @@ export interface CodexCliIntelligenceProviderOptions {
      */
     sandboxMode?: 'read-only' | 'workspace-write' | 'danger-full-access';
     /**
-     * Working directory for the codex CLI invocation. Defaults to
-     * process.cwd(). Reviewer / canary calls don't depend on cwd content
-     * but Codex CLI honors the flag so it's safe to pass.
+     * Retained for API compatibility. NOTE: this is intentionally NOT used as
+     * the `codex exec --cd` for judgment calls. Those always run in an empty
+     * instar-managed scratch dir (see `resolveIntelligenceScratchDir`) so the
+     * agent's project identity + hooks never load. These calls don't depend on
+     * cwd content, so ignoring this value is safe.
      */
     workingDirectory?: string;
 }
 export declare class CodexCliIntelligenceProvider implements IntelligenceProvider {
     private readonly codexPath;
     private readonly sandboxMode;
-    private readonly workingDirectory;
     constructor(options: CodexCliIntelligenceProviderOptions);
     evaluate(prompt: string, options?: IntelligenceOptions): Promise<string>;
 }

package/dist/core/CodexCliIntelligenceProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CodexCliIntelligenceProvider.d.ts","sourceRoot":"","sources":["../../src/core/CodexCliIntelligenceProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAM5E,MAAM,WAAW,mCAAmC;IAClD,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,WAAW,CAAC,EAAE,WAAW,GAAG,iBAAiB,GAAG,oBAAoB,CAAC;IACrE;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,qBAAa,4BAA6B,YAAW,oBAAoB;IACvE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAyD;IACrF,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;gBAE9B,OAAO,EAAE,mCAAmC;IAMlD,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC;CAkE/E"}
+{"version":3,"file":"CodexCliIntelligenceProvider.d.ts","sourceRoot":"","sources":["../../src/core/CodexCliIntelligenceProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AA6C5E,MAAM,WAAW,mCAAmC;IAClD,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,WAAW,CAAC,EAAE,WAAW,GAAG,iBAAiB,GAAG,oBAAoB,CAAC;IACrE;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,qBAAa,4BAA6B,YAAW,oBAAoB;IACvE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAyD;gBAEzE,OAAO,EAAE,mCAAmC;IASlD,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC;CA6E/E"}

package/dist/core/CodexCliIntelligenceProvider.js

@@ -12,26 +12,78 @@
  * implementation based on the agent's configured framework.
  */
 import { execFile } from 'node:child_process';
+import { mkdtempSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { resolveCliModelFlag } from '../providers/adapters/openai-codex/models.js';
 import { buildCodexChildEnv } from '../providers/adapters/openai-codex/transport/codexSpawn.js';
 const DEFAULT_TIMEOUT_MS = 30_000;
+const INTELLIGENCE_SCRATCH_DIR_PREFIX = 'instar-codex-intel-scratch-';
+let cachedScratchDir = null;
+/**
+ * Lazily create and return an EMPTY scratch directory used as the `--cd`
+ * for every judgment call.
+ *
+ * Running `codex exec` in the agent's project directory loads the full
+ * ~26 KB `AGENTS.md` identity AND fires the project's `.codex/hooks.json`
+ * hooks (session_start / user_prompt_submit / stop) on every call — turning
+ * a one-word classification into a full agent boot. An empty, hook-free
+ * scratch dir gives these calls the clean-notepad guarantee that
+ * `ClaudeCliIntelligenceProvider` gets via `--setting-sources user`:
+ * no project doc, and no project hooks.
+ *
+ * SECURITY (why mkdtemp, not a fixed name): Codex discovers hooks by walking
+ * UP from the cwd and fires any `.codex/hooks.json` it finds — and
+ * `project_doc_max_bytes=0` does NOT cover hooks. On Linux `os.tmpdir()` is
+ * the world-writable `/tmp`, so a fixed, guessable dir name could be
+ * pre-created (or symlinked) by another local user with a planted
+ * `.codex/hooks.json`, re-introducing hook execution under our identity.
+ * `mkdtempSync` defeats this: it appends an unguessable random suffix, creates
+ * the dir with mode 0700 owned by this process, and refuses to follow a
+ * pre-existing path — so nothing can be planted in the cwd these calls run in.
+ *
+ * The dir is re-verified each call: a tmp-reaper may delete it during a
+ * long-lived process, so we recreate it if it has gone missing.
+ *
+ * Bug (2026-05-26): ~1,550 such judgment spawns/day were re-injecting the
+ * identity + firing session_start, causing notification spam and spawn-storm
+ * delivery failures. Spec: CODEX-INTELLIGENCE-PROVIDER-CLEAN-CALL-SPEC.md.
+ */
+function resolveIntelligenceScratchDir() {
+    if (cachedScratchDir && existsSync(cachedScratchDir))
+        return cachedScratchDir;
+    cachedScratchDir = mkdtempSync(join(tmpdir(), INTELLIGENCE_SCRATCH_DIR_PREFIX));
+    return cachedScratchDir;
+}
 export class CodexCliIntelligenceProvider {
     codexPath;
     sandboxMode;
-    workingDirectory;
     constructor(options) {
         this.codexPath = options.codexPath;
         this.sandboxMode = options.sandboxMode ?? 'read-only';
-        this.workingDirectory = options.workingDirectory ?? process.cwd();
+        // options.workingDirectory is intentionally NOT stored: judgment calls
+        // always run in an empty scratch dir (resolveIntelligenceScratchDir), so
+        // the agent's project identity + hooks never load. The option is retained
+        // on the type for API compatibility (the factory still forwards it).
     }
     async evaluate(prompt, options) {
         const model = resolveCliModelFlag(options?.model);
+        const scratchDir = resolveIntelligenceScratchDir();
         return new Promise((resolve, reject) => {
             const args = [
                 'exec',
                 '--model', model,
                 '--sandbox', this.sandboxMode,
-                '--cd', this.workingDirectory,
+                // Run judgment calls in an empty scratch dir, NOT the agent's project
+                // dir. The project dir loads the full ~26 KB AGENTS.md identity AND
+                // fires the project's .codex/hooks.json (session_start /
+                // user_prompt_submit / stop) on every call. The scratch dir is the
+                // Codex analog of ClaudeCliIntelligenceProvider's `--setting-sources
+                // user`. See resolveIntelligenceScratchDir + the spec.
+                '--cd', scratchDir,
+                // Belt-and-suspenders: hard-disable project-doc (AGENTS.md) loading
+                // even if a stray doc ever lands at or above the scratch path.
+                '-c', 'project_doc_max_bytes=0',
                 // Reviewer/sentinel/canary calls are deterministic short prompts
                 // that don't depend on the cwd being a trusted git repo. Codex
                 // CLI's default behavior is to refuse to run when --cd points at

package/dist/core/CodexCliIntelligenceProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"CodexCliIntelligenceProvider.js","sourceRoot":"","sources":["../../src/core/CodexCliIntelligenceProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAC;AACnF,OAAO,EAAE,kBAAkB,EAAE,MAAM,4DAA4D,CAAC;AAEhG,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAmBlC,MAAM,OAAO,4BAA4B;IACtB,SAAS,CAAS;IAClB,WAAW,CAAyD;IACpE,gBAAgB,CAAS;IAE1C,YAAY,OAA4C;QACtD,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QACnC,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,WAAW,CAAC;QACtD,IAAI,CAAC,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IACpE,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,MAAc,EAAE,OAA6B;QAC1D,MAAM,KAAK,GAAG,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAElD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,MAAM,IAAI,GAAG;gBACX,MAAM;gBACN,SAAS,EAAE,KAAK;gBAChB,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,MAAM,EAAE,IAAI,CAAC,gBAAgB;gBAC7B,iEAAiE;gBACjE,+DAA+D;gBAC/D,iEAAiE;gBACjE,sCAAsC;gBACtC,kFAAkF;gBAClF,6DAA6D;gBAC7D,iEAAiE;gBACjE,4BAA4B;gBAC5B,uBAAuB;gBACvB,6DAA6D;gBAC7D,gEAAgE;gBAChE,gEAAgE;gBAChE,YAAY;gBACZ,MAAM;aACP,CAAC;YAEF,mEAAmE;YACnE,uEAAuE;YACvE,mEAAmE;YACnE,oEAAoE;YACpE,mEAAmE;YACnE,qEAAqE;YACrE,2DAA2D;YAC3D,EAAE;YACF,kEAAkE;YAClE,iEAAiE;YACjE,kEAAkE;YAClE,MAAM,QAAQ,GAAG,kBAAkB,EAAE,CAAC;YAEtC,MAAM,KAAK,GAAG,QAAQ,CACpB,IAAI,CAAC,SAAS,EACd,IAAI,EACJ;gBACE,OAAO,EAAE,kBAAkB;gBAC3B,SAAS,EAAE,IAAI,GAAG,IAAI;gBACtB,GAAG,EAAE,QAAQ;aACd,EACD,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE;gBACxB,IAAI,KAAK,EAAE,CAAC;oBACV,MAAM,CACJ,IAAI,KAAK,CACP,oBAAoB,KAAK,CAAC,OAAO,EAAE;wBACjC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAC/C,CACF,CAAC;oBACF,OAAO;gBACT,CAAC;gBACD,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;YACzB,CAAC,CACF,CAAC;YAEF,iEAAiE;YACjE,kEAAkE;YAClE,kEAAkE;YAClE,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC;QACrB,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}
+{"version":3,"file":"CodexCliIntelligenceProvider.js","sourceRoot":"","sources":["../../src/core/CodexCliIntelligenceProvider.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "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-05-26T20:50:07.446Z",
-  "instarVersion": "1.3.1",
+  "generatedAt": "2026-05-26T21:00:08.875Z",
+  "instarVersion": "1.3.2",
   "entryCount": 192,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.2.md

@@ -0,0 +1,49 @@
+# Upgrade Guide — NEXT
+
+<!-- bump: patch -->
+<!-- Valid values: patch, minor, major -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+<!-- minor = new features, new APIs, new capabilities (backwards-compatible) -->
+<!-- major = breaking changes to existing APIs or behavior -->
+
+## What Changed
+
+**Codex-powered agents stop reloading their full identity on every background "judgment" call.** Instar makes ~1,500+ tiny internal LLM calls per agent per day — classify this message, did that turn finish, summarize this chunk, extract the intent. On a Codex-powered agent, each of those ran `codex exec` *inside the agent's project directory*, which made Codex load the agent's entire ~26 KB `AGENTS.md` identity AND fire the project's `.codex/hooks.json` (session_start / user_prompt_submit / stop) **every single time** — just to answer one word like "normal."
+
+This was the dominant cause of two visible problems on Codex agents: the flood of "actively working / message delivered / still working" notifications (the session_start hook firing on ~1,550 spawns/day, so the monitoring layer thought a real session was constantly starting), and intermittent "couldn't deliver — please resend" failures (a dozen of these heavyweight spawns landing in one minute saturated the machine so a real inbound message couldn't get a process slot).
+
+The fix gives those calls a clean notepad — the Codex analog of what `ClaudeCliIntelligenceProvider` already does with `--setting-sources user`. `CodexCliIntelligenceProvider` now runs judgment calls in an empty, private (0700, unguessable-name via `mkdtempSync`) scratch directory instead of the project dir, plus `-c project_doc_max_bytes=0`. No identity load, no project hooks. Claude-powered agents are unaffected (they were already clean).
+
+## Evidence
+
+Reproduced live on this machine's Codex install (codex-cli 0.133.0), before/after.
+
+**Before (production incident, 2026-05-25 rollout logs in `~/.codex/sessions/`):** 1,601
+`codex exec` spawns in one day, ~1,550 of them internal judgment calls. A sampled
+message-classifier rollout (21:52) re-injected the full ~26 KB `AGENTS.md` identity AND a
+`SESSION START` block — firing session_start — just to output the single word `normal`.
+Those rollouts ran with `cwd` = the agent's project dir and were 63–110 KB each.
+
+**After (controlled run of the built fixed provider against the real codex binary,
+2026-05-26 13:49):** called `CodexCliIntelligenceProvider.evaluate()` with a unique marker
+prompt; located the exact rollout it produced
+(`rollout-2026-05-26T13-49-18-…019e660c….jsonl`). Observed:
+- `cwd` = `/var/folders/…/T/instar-codex-intel-scratch-AOYJWS` (the mkdtemp scratch dir) ✓
+- `AGENTS.md instructions` blocks: **0** (was ≥1) ✓
+- `SESSION START` blocks: **0** (was 1) ✓
+- `CURRENT TIME` hook markers (user_prompt_submit): **0** ✓
+- rollout size 29.6 KB (was 63–110 KB) — the residue is codex's own base prompt, not instar identity.
+
+The identity load and the session_start/user_prompt_submit hook firing are gone for
+judgment calls. The agent still returned the correct answer.
+
+## What to Tell Your User
+
+- **If you run a Codex-powered agent, it should get noticeably quieter and more reliable — no action needed.** The "still working" notification spam and the occasional dropped/"please resend" messages were mostly this one plumbing bug; the agent was effectively re-reading its whole identity ~1,500 times a day. Claude-powered agents won't notice anything (they were never affected).
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Codex judgment calls run identity-free + hook-free | Automatic. `CodexCliIntelligenceProvider` runs `codex exec` in an empty `mkdtempSync` scratch dir + `-c project_doc_max_bytes=0` instead of the project dir. |
+| Hardened scratch dir | Automatic. Unguessable random name, 0700 perms, recreated if a tmp-reaper deletes it — nothing can be planted in the cwd these calls run from. |

package/upgrades/side-effects/fix-codex-intel-clean-call.md

@@ -0,0 +1,108 @@
+# Side-Effects Review — Codex Intelligence-Provider Clean-Call Fix
+
+**Version / slug:** `fix-codex-intel-clean-call`
+**Date:** 2026-05-26
+**Author:** Echo
+**Spec:** `docs/specs/CODEX-INTELLIGENCE-PROVIDER-CLEAN-CALL-SPEC.md` (converged + approved)
+
+## Summary of the change
+
+`CodexCliIntelligenceProvider.evaluate()` ran `codex exec --cd <agent project dir>` for
+every internal LLM "judgment" call (message classification, terminal-output analysis,
+arc extraction, usher, coherence, etc.). Running in the project dir made Codex load the
+full ~26 KB `AGENTS.md` identity AND fire the project's `.codex/hooks.json`
+(session_start / user_prompt_submit / stop) on **every** call — ~1,550 such calls/day,
+causing notification spam (session_start firing constantly) and spawn-storm delivery
+failures (12 heavyweight spawns/minute saturating the machine).
+
+The fix runs these calls in an empty, owner-only scratch dir instead — the Codex analog
+of `ClaudeCliIntelligenceProvider`'s `--setting-sources user`. No identity, no project
+hooks.
+
+**Files changed (source):**
+- `src/core/CodexCliIntelligenceProvider.ts` — `evaluate()` now uses an `mkdtempSync`
+  scratch dir for `--cd` (not the project dir) + `-c project_doc_max_bytes=0`; added the
+  `resolveIntelligenceScratchDir()` helper; removed the now-dead `workingDirectory` field
+  (kept on the options type for API compat).
+
+**Files changed (tests):**
+- `tests/unit/CodexCliIntelligenceProvider.test.ts` — updated the `--cd` assertion (it
+  previously asserted the buggy project-dir behavior) + added 7 cases covering the
+  scratch-dir contract, 0700 perms, unguessable name, and tmp-reaper recovery (12 total).
+
+**Files changed (spec / report / release notes):**
+- `docs/specs/CODEX-INTELLIGENCE-PROVIDER-CLEAN-CALL-SPEC.md` (+ `.eli16.md`)
+- `docs/specs/reports/codex-intelligence-provider-clean-call-convergence.md`
+- `upgrades/NEXT.md`
+
+## Decision-point inventory
+
+- **Scratch dir, not the project dir** — the core fix. Judgment calls are cwd-independent
+  (per the existing code comment), so an empty cwd is correct.
+- **`mkdtempSync` (random suffix, 0700), not a fixed name** — convergence security finding:
+  a fixed `/tmp` name on Linux is plantable (`.codex/hooks.json` squatting; not gated by
+  `project_doc_max_bytes`). The unguessable, owner-only dir closes that vector.
+- **Re-verify-before-use** — recreate the dir if a tmp-reaper deleted it during a
+  long-lived process.
+- **`-c project_doc_max_bytes=0`** — belt-and-suspenders for an `AGENTS.md` on the cwd
+  walk-up; real key, already used in `contextScopeControl.ts`.
+- **Drop `workingDirectory` as exec cwd** — verified only `route.ts` passes it, and only
+  for its own PreferenceStore DB path, never the codex cwd.
+
+## Over-block / under-block analysis
+
+- **Over-block:** none. The provider gates nothing; it only changes the cwd of a spawn.
+  Judgment calls that worked before continue to work (the fake-codex unit tests confirm
+  the full arg contract).
+- **Under-block:** the *intended* behavioral subtraction is "stop loading identity + firing
+  hooks for judgment calls." There is no path where a judgment call legitimately needed the
+  identity or hooks — they are stateless classifications/extractions. If a future caller
+  did need project context, it must pass it in the prompt (as all current callers do), not
+  rely on cwd.
+
+## Level-of-abstraction fit
+
+The fix lives in the single provider that owns the `codex exec` invocation — the same layer
+where the Claude sibling already solves the identical problem with `--setting-sources user`.
+No higher-level orchestration or config knob is introduced; the concern is local to the
+spawn, so the fix is local to the spawn. Correct altitude.
+
+## Signal-vs-authority compliance
+
+N/A in the gate sense — this change neither detects nor blocks anything. It is a pure
+invocation-hygiene fix. It does not touch any sentinel/gate authority boundary.
+
+## Interactions
+
+- **Claude provider:** untouched; asymmetry (flag vs scratch-cwd) is intentional and
+  documented — Codex has no single equivalent flag.
+- **Callers (`reflect.ts`, `route.ts`, `server.ts`):** none depend on the codex cwd
+  content; verified during integration review. No behavior change for them beyond the
+  intended one.
+- **Concurrency:** `mkdtempSync` once + cached + `existsSync` re-check; no race under the
+  high call volume (idempotent, read-only dir).
+- **Monitoring layer:** positive interaction — the session_start hook no longer fires on
+  judgment spawns, so PresenceProxy/standby stops mistaking them for real sessions
+  (the notification-spam root cause).
+
+## Rollback cost
+
+Trivial and isolated. Revert the single source file (and its test). No persisted state, no
+schema, no config/hook/template/migration to unwind — the only on-disk footprint is an
+empty 0700 tmp dir that the OS reaps on its own. Reverting restores the prior (buggy but
+functional) behavior with zero data implications.
+
+## Migration parity
+
+Code-only change inside the compiled provider. No agent-installed file
+(settings/hooks/config/templates/skills) references the old behavior, so **no
+`PostUpdateMigrator` entry is required** — existing Codex agents receive the fix via the
+normal package update path. Verified by grep during integration review.
+
+## Testing evidence
+
+- Unit: 12 tests in `CodexCliIntelligenceProvider.test.ts` pass; sibling env-allowlist (4)
+  + factory (10) tests unaffected; clean `tsc` build.
+- Live / bug-fix evidence bar: the before/after rollout reproduction on a real Codex agent
+  (identity-loaded before, bare after) is run as the post-merge test-as-self gate and
+  recorded before the fix is declared shipped.