iranti 0.2.51 → 0.3.2

package/README.md

@@ -9,10 +9,11 @@
 
 Iranti gives agents persistent, identity-based memory. Facts written by one agent are retrievable by any other agent through exact entity+key lookup. Iranti also supports hybrid search (lexical + vector) when exact keys are unknown. Memory persists across sessions and survives context window limits.
 
-**Latest release:** [`v0.2.49`](https://github.com/nfemmanuel/iranti/releases/tag/v0.2.49)  
+**Repo version:** `0.3.0`  
 Published packages:
-- `iranti@0.2.49`
-- `@iranti/sdk@0.2.49`
+- npm `iranti@0.3.0`
+- npm `@iranti/sdk@0.3.0`
+- PyPI `iranti==0.3.0`
 
 ---
 
@@ -52,25 +53,29 @@ Vector databases answer "what's similar to X?" Iranti answers "what do we know a
 
 ## Benchmark Summary
 
-Iranti has now been rerun against a broader benchmark program covering 11 active capability tracks in `v0.2.21`. The current picture is stronger and narrower than the early validation story: exact, durable, shared memory is benchmark-backed; broad semantic-memory and autonomous-memory claims still need tighter boundaries.
+Iranti now has current rerun evidence across exact retrieval, process continuity, upgrade durability, relationships, bounded conflict handling, and bounded recovery behavior. The current picture is stronger and narrower than the early validation story: exact, durable, shared memory is validated; broad semantic-memory and autonomous-recovery claims still need explicit limits.
 
 ### Confirmed Strengths
 
-- **Exact lookup (`iranti_query`)**: Retrieval remains exact and durable across genuine session and process breaks. At tested scale (`N=1938`, about `107k` tokens), the measured advantage is efficiency, not accuracy: Iranti answered `10/10` with zero haystack tokens while the baseline also answered `10/10` after reading the full document.
-- **Persistence across sessions**: Facts survive context-window loss and genuine process boundaries. `iranti_query` remained `8/8` across isolated session breaks in the rerun.
+- **Exact lookup (`iranti_query`)**: The prepublish candidate for the current `0.3.0` line still scored `10/10` on the canonical B1 exact-retrieval arm.
+- **Persistence across sessions and processes**: Facts survive context-window loss and genuine process boundaries, with current reruns and validation passes covering process-isolated reads plus cross-process invalidation.
+- **Upgrade durability**: A fresh continuity chain now passes across public npm `0.2.49 -> 0.2.50 -> 0.2.51` plus a final prepublish candidate hop on the `0.3.0` line.
 - **Conflict handling**: Reliable when confidence differentials are large and explicit.
-- **Multi-agent coordination**: Agents can share memory across genuine subprocess boundaries with zero shared conversational context.
+- **Relationship traversal and multi-agent coordination**: Relationship writes plus one-hop/deep traversal work, and agents can share memory across genuine subprocess boundaries with zero shared conversational context.
 - **Provenance on writes**: Write-side attribution through stored source metadata is working and benchmark-confirmed.
-- **Ingest**: Prose extraction is accurate on clean entities in `v0.2.21`. Reliability under conflict-heavy transactional conditions should still be treated as a separate, narrower claim.
-- **Observe with hints**: `iranti_observe` recovers facts reliably when given the right entity hint, with higher-confidence facts returned first.
-- **Session recovery**: Interrupted-session recovery now performs substantially better than baseline.
+- **Ingest**: Prose extraction is accurate on clean entities in the bounded rerun surfaces already documented.
+- **Observe with hints / explicit recovery**: `iranti_observe` with hints and explicit query-based recovery are meaningfully useful today.
+- **Protocol enforcement turn-gate**: Strict turn-cycle enforcement (handshake → attend → discover → post-response) is validated by focused route and MCP regression tests. In `strict` mode, KB discovery routes return HTTP 428 with a structured violation payload before an agent that skipped attend can silently read stale memory. Injected facts now include a `lastUpdated` timestamp so the calling agent can judge freshness at the point of injection.
+
+Recent fixes since the last rerun:
+- **Search now bridges semantic hits across relationships for filtered retrieval.** A strong incident or issue hit can now propagate back onto the owning filtered entity over up to two hops, so filtered project search no longer depends on direct lexical overlap alone.
+- **`iranti_attend` now safe-defaults parse failures toward memory on non-greeting turns.** Terse prompts such as `help`, `why?`, or `how?` no longer silently fall through to `classification_parse_failed_default_false`.
+- **Hybrid search now indexes entity addresses directly.** Addressed queries such as `project/<id> status` no longer rely on value-summary overlap alone.
 
 ### Current Limits
 
-- **Search is lexical-first today, not semantic multi-hop retrieval.** In the current rerun, hop-value discovery was `0/4`; bare entity-token lookup worked, but `vectorScore` stayed `0` across results.
-- **`iranti_attend` is not yet a reliable autonomous classifier.** Natural-language attend classification still falls back to `classification_parse_failed_default_false`; `forceInject` works as an operator bypass, not as proof of autonomous injection.
-- **Observe performs better with explicit entity hints than with cold-start discovery.**
-- **Upgrade durability should be scoped carefully.** The `v0.2.21` upgrade procedure reinitialized the instance under test; do not assume KB data survives upgrades without an explicit preservation or migration path.
+- **Upgrade durability is now test-covered.** The `v0.2.21` upgrade reinitialized the instance under test — a one-time operator incident, not a systemic design flaw. All Prisma migrations are additive (no DROP or TRUNCATE); Staff Namespace seeding is guarded by `isSeeded()`; `seed-codebase.ts` upserts to `codebase/*` entities only. A KB preservation test in `tests/runtime-lifecycle/run_setup_upgrade_tests.ts` now confirms user KB data written before a `setup` re-run survives intact.
+- **Project learning is now only a bounded bind-time snapshot.** When you bind a project, Iranti derives a stable `IRANTI_CODEBASE_ENTITY` and writes a small snapshot from authoritative files such as `package.json`, `README.md`, `tsconfig.json`, `pyproject.toml`, `prisma/schema.prisma`, and common source directories. It does not yet crawl the repo continuously or build autonomous whole-project understanding.
 - **Relationship and provenance reflection surfaces remain partially permission-gated in benchmark sessions.** The rerun did not prove `iranti_relate`, `iranti_related`, `iranti_related_deep`, or `iranti_who_knows` end-to-end under the benchmark session policy.
 
 ### Practical Position
@@ -78,9 +83,10 @@ Iranti has now been rerun against a broader benchmark program covering 11 active
 Iranti is strongest today as **structured memory infrastructure for multi-agent systems**:
 - exact entity/key lookup
 - durable shared memory
-- provenance-aware writes
+- provenance-aware writes with source attribution and freshness timestamps
 - conflict-aware storage
 - session-aware recovery
+- protocol-enforced turn discipline for trustworthy injection (opt-in strict mode)
 
 It should not yet be described as a fully general semantic-memory, semantic-search, or autonomous-memory-injection system.
 
@@ -465,6 +471,7 @@ iranti project init . --instance local --agent-id chatbot_main
 ```
 
 This writes `.env.iranti` in the project with the correct `IRANTI_URL`, `IRANTI_API_KEY`, and default agent identity.
+It also writes a derived `IRANTI_CODEBASE_ENTITY` and a bounded initial project snapshot for that bound repo.
 
 Later changes use the same surface:
 
@@ -607,13 +614,16 @@ for item in matches:
 
 ### Context Persistence (attend)
 
+`handshake()` establishes the session contract. Discovery surfaces such as `query`, `search`, `get_related`, and `who_knows` are now fail-closed until the host has run `handshake()` for the session and `attend()` for the current turn. Starting a new `attend(phase="pre-response")` turn without first closing the previous one with `attend(phase="post-response")` is now blocked as a protocol violation, and `inspectSession()` / `listSessions()` expose structured lifecycle compliance state (`healthy`, `degraded`, `non_compliant`) so hosts and operators can see when breadcrumb discipline is slipping.
+
 ```python
 # Before each LLM call, let Attendant decide if memory is needed
 result = client.attend(
     agent_id="research_agent_001",
     latest_message="What's Jane Smith's current affiliation?",
     current_context="User: What's Jane Smith's current affiliation?\nAssistant: Let me check...",
-    max_facts=5
+    max_facts=5,
+    phase="pre-response"
 )
 
 if result["shouldInject"]:
@@ -729,6 +739,7 @@ middleware.after_receive(
 1. `before_send()` calls `attend()` with conversation context
 2. Forgotten facts are prepended as `[MEMORY: ...]`
 3. `after_receive()` extracts new facts and saves them (best-effort)
+4. If the host skips `handshake()` or `attend()`, discovery calls block instead of returning warn-only metadata
 
 **Note**: Browser extensions are blocked by ChatGPT and Claude's Content Security Policy. Use API-based middleware instead.
 
@@ -757,9 +768,10 @@ Express server on port 3001 with endpoints:
 - `GET /kb/query/:entityType/:entityId/:key` - Query specific fact
 - `GET /kb/query/:entityType/:entityId` - Query all facts for entity
 - `GET /kb/search` - Hybrid search across facts
-- `POST /memory/attend` - Decide whether to inject memory for this turn
+- `POST /memory/attend` - Decide whether to inject memory for this turn and unlock one discovery step for the current turn
 - `POST /memory/observe` - Context persistence (inject missing facts)
 - `POST /memory/handshake` - Working memory brief for agent session
+- `GET /memory/ledger` - Read structured session ledger events from `staff_events`
 - `GET /memory/sessions` - List persisted operator-visible session checkpoints across agents, with optional operator filters/sorting
 - `GET /memory/session/:agentId` - Inspect the current persisted session checkpoint/recovery state
 - `POST /kb/relate` - Create entity relationship
@@ -767,6 +779,7 @@ Express server on port 3001 with endpoints:
 - `POST /agents/register` - Register agent in registry
 
 All endpoints require `X-Iranti-Key` header for authentication.
+Discovery endpoints return `428 Precondition Required` when a host skips the required session `handshake` or current-turn `attend`.
 
 ---
 

package/dist/scripts/api-key-create.js

@@ -27,7 +27,7 @@ async function main() {
         console.error('DATABASE_URL is required.');
         process.exit(1);
     }
-    (0, client_1.initDb)(dbUrl);
+    (0, client_1.initDb)(dbUrl, { applicationName: 'iranti:script:api_key_create' });
     const created = await (0, apiKeys_1.createOrRotateApiKey)({
         keyId,
         owner,

package/dist/scripts/api-key-list.js

@@ -9,7 +9,7 @@ async function main() {
         console.error('DATABASE_URL is required.');
         process.exit(1);
     }
-    (0, client_1.initDb)(dbUrl);
+    (0, client_1.initDb)(dbUrl, { applicationName: 'iranti:script:api_key_list' });
     const keys = await (0, apiKeys_1.listApiKeys)();
     if (keys.length === 0) {
         console.log('No registry API keys found.');

package/dist/scripts/api-key-revoke.js

@@ -20,7 +20,7 @@ async function main() {
         console.error('DATABASE_URL is required.');
         process.exit(1);
     }
-    (0, client_1.initDb)(dbUrl);
+    (0, client_1.initDb)(dbUrl, { applicationName: 'iranti:script:api_key_revoke' });
     const revoked = await (0, apiKeys_1.revokeApiKey)(keyId);
     if (!revoked) {
         console.error(`API key not found: ${keyId}`);

package/dist/scripts/claude-code-memory-hook.js

@@ -9,7 +9,10 @@ const path_1 = __importDefault(require("path"));
 const createFirstPartyIranti_1 = require("../src/lib/createFirstPartyIranti");
 const runtimeEnv_1 = require("../src/lib/runtimeEnv");
 const staffEventRegistry_1 = require("../src/lib/staffEventRegistry");
+const client_1 = require("../src/library/client");
 const autoRemember_1 = require("../src/lib/autoRemember");
+const assistantCheckpoint_1 = require("../src/lib/assistantCheckpoint");
+const hostMemoryFormatting_1 = require("../src/lib/hostMemoryFormatting");
 const MEMORY_NEED_POSITIVE_PATTERNS = [
     /\bwhat(?:'s| is| was)?\s+my\b/i,
     /\bdo you remember\b/i,
@@ -40,7 +43,7 @@ function printHelp() {
         '',
         'Reads Claude Code hook JSON from stdin and returns hookSpecificOutput.additionalContext on stdout.',
         'This helper retrieves working memory; durable KB writes still require explicit iranti_write/ingest calls.',
-        'Set IRANTI_AUTO_REMEMBER=true to auto-save narrow personal facts to IRANTI_PERSONAL_MEMORY_ENTITY/user/main and project summaries to IRANTI_MEMORY_ENTITY.',
+        'Set IRANTI_AUTO_REMEMBER=true to auto-save prompt-side personal/project facts. Assistant-response continuity facts and shared checkpoints are captured on Stop regardless.',
     ].join('\n'));
 }
 function parseArgs(argv) {
@@ -228,19 +231,39 @@ function getMaxFacts() {
     return Math.min(12, Math.trunc(raw));
 }
 function formatSessionContext(facts, cwd) {
-    const limited = facts.slice(0, getMaxFacts());
+    const limited = (0, hostMemoryFormatting_1.assignStructuredFactIds)(facts.slice(0, getMaxFacts()).map((fact) => ({
+        ...fact,
+        entityKey: `${fact.entity}/${fact.key}`,
+    })));
     const lines = [
         '[Iranti Session Memory]',
         `Project: ${path_1.default.basename(cwd)}`,
+        'REQUIRED: Call mcp__iranti__iranti_handshake before responding to the first user message.',
+        'REQUIRED: Call mcp__iranti__iranti_attend(phase=\'pre-response\') before every reply and before factual discovery.',
+        'REQUIRED: After every response, call mcp__iranti__iranti_attend(phase=\'post-response\').',
+        'REQUIRED: Prefer injected Iranti facts before re-inferring project state.',
     ];
-    if (limited.length > 0) {
-        lines.push('Relevant memory:');
-        for (const fact of limited) {
-            lines.push(`- ${fact.entity}/${fact.key}: ${fact.summary}`);
-        }
-    }
+    const block = (0, hostMemoryFormatting_1.formatStructuredFactBlock)(limited, {
+        title: 'Iranti Session Facts',
+        introLines: [
+            'Use these loaded facts as the starting working-memory frame for this session.',
+            'Prefer them before re-inferring project state.',
+            'Fact IDs are stable only within this block.',
+        ],
+    });
+    if (block)
+        lines.push(block);
     return lines.join('\n');
 }
+function formatPreCompactContext() {
+    return [
+        '[Iranti Post-Compaction Recovery]',
+        'Context was just compacted. BEFORE responding to the next user message:',
+        '1. Call mcp__iranti__iranti_handshake with the current task to restore working memory.',
+        '2. Do not respond until the handshake completes.',
+        'REQUIRED: Call mcp__iranti__iranti_attend before every subsequent turn after that.',
+    ].join('\n');
+}
 function extractSelfMemoryQueryKey(prompt) {
     const normalized = prompt.trim();
     if (!normalized)
@@ -258,18 +281,20 @@ function extractSelfMemoryQueryKey(prompt) {
 function formatPromptContext(facts, prompt) {
     if (facts.length === 0)
         return '';
-    const lines = ['[Iranti Retrieved Memory]'];
+    const structuredFacts = (0, hostMemoryFormatting_1.assignStructuredFactIds)(facts.map((fact) => ({
+        ...fact,
+        entityKey: `${fact.entity}/${fact.key}`,
+    })));
+    const lines = [];
     const targetKey = prompt ? extractSelfMemoryQueryKey(prompt) : null;
     if (targetKey) {
-        const answerCandidate = facts.find((fact) => (0, autoRemember_1.canonicalizeMemoryKey)(fact.key) === targetKey);
+        const answerCandidate = structuredFacts.find((fact) => (0, autoRemember_1.canonicalizeMemoryKey)(fact.entityKey.split('/').slice(2).join('/')) === targetKey);
         if (answerCandidate) {
-            lines.push(`Direct answer: ${answerCandidate.summary}.`);
-            lines.push('Use the direct answer above when it fully answers the user question.');
+            lines.push(`[Iranti Direct Answer]`);
+            lines.push(`Use ${answerCandidate.factId} directly if it fully answers the user question: ${answerCandidate.summary}.`);
         }
     }
-    for (const fact of facts) {
-        lines.push(`- ${fact.entity}/${fact.key}: ${fact.summary}`);
-    }
+    lines.push((0, hostMemoryFormatting_1.formatStructuredFactBlock)(structuredFacts, { title: 'Iranti Retrieved Memory' }));
     return lines.join('\n');
 }
 function emitHookContext(event, additionalContext) {
@@ -285,6 +310,10 @@ function shouldFetchMemory(prompt) {
     const normalized = prompt.trim();
     if (!normalized)
         return false;
+    const explicitFacts = (0, autoRemember_1.extractExplicitPromptMemory)(normalized);
+    if (explicitFacts.some((fact) => fact.scope === 'project')) {
+        return false;
+    }
     if (MEMORY_NEED_NEGATIVE_PATTERNS.some((pattern) => pattern.test(normalized))) {
         return false;
     }
@@ -294,7 +323,12 @@ function shouldFetchMemory(prompt) {
     if (/\b(my|our|we)\b/i.test(normalized)) {
         return true;
     }
-    return normalized.includes('/');
+    if (normalized.includes('/')) {
+        return true;
+    }
+    // Any substantive prompt in a project context should trigger memory fetch.
+    // Short acks and filler are already caught by MEMORY_NEED_NEGATIVE_PATTERNS.
+    return normalized.length > 20;
 }
 function dedupeFacts(facts) {
     const byKey = new Map();
@@ -351,6 +385,9 @@ async function buildHookAdditionalContext(options) {
     const cwd = getCwd(payload);
     const agent = await ensureHookAgent(iranti, payload);
     const entityHints = getEntityHints(payload);
+    if (event === 'PreCompact') {
+        return formatPreCompactContext();
+    }
     if (event === 'SessionStart') {
         const brief = await iranti.handshake({
             agent,
@@ -365,12 +402,37 @@ async function buildHookAdditionalContext(options) {
     }
     if (event === 'Stop') {
         const response = getLastAssistantMessage(payload);
-        if (response && (0, autoRemember_1.isAutoRememberEnabled)()) {
-            await (0, autoRemember_1.autoRememberAssistantFacts)({
+        if (response) {
+            await (0, autoRemember_1.rememberAssistantResponseFacts)({
                 iranti,
                 response,
                 agent,
                 source: 'ClaudeCodeHookStop',
+                ledgerContext: {
+                    source: 'claude_hook',
+                    host: 'claude_code',
+                },
+            });
+            const checkpoint = (0, assistantCheckpoint_1.extractAssistantCheckpointPayload)(response);
+            const projectEntity = (0, autoRemember_1.getProjectMemoryEntity)();
+            if (checkpoint && projectEntity && typeof iranti.checkpoint === 'function') {
+                await iranti.checkpoint({
+                    agent,
+                    task: buildSessionTask(payload),
+                    recentMessages: getRecentMessages(payload),
+                    checkpoint: {
+                        ...checkpoint,
+                        entityTargets: [projectEntity],
+                    },
+                });
+            }
+            await iranti.attend({
+                agent,
+                latestMessage: response,
+                currentContext: response,
+                entityHints,
+                maxFacts: getMaxFacts(),
+                phase: 'post-response',
             });
         }
         return '';
@@ -385,6 +447,10 @@ async function buildHookAdditionalContext(options) {
             prompt,
             agent,
             source: 'ClaudeCodeHook',
+            ledgerContext: {
+                source: 'claude_hook',
+                host: 'claude_code',
+            },
         });
     }
     if (!shouldFetchMemory(prompt)) {
@@ -396,6 +462,7 @@ async function buildHookAdditionalContext(options) {
         currentContext: buildCurrentContext(payload, prompt),
         entityHints,
         maxFacts: getMaxFacts(),
+        phase: 'pre-response',
     });
     const facts = attend.facts.map((fact) => ({
         entity: fact.entityKey.split('/').slice(0, 2).join('/'),
@@ -413,8 +480,8 @@ async function main() {
     }
     const args = parseArgs(process.argv.slice(2));
     const event = args.event;
-    if (event !== 'SessionStart' && event !== 'UserPromptSubmit' && event !== 'Stop') {
-        throw new Error('--event must be SessionStart, UserPromptSubmit, or Stop');
+    if (event !== 'SessionStart' && event !== 'UserPromptSubmit' && event !== 'Stop' && event !== 'PreCompact') {
+        throw new Error('--event must be SessionStart, UserPromptSubmit, Stop, or PreCompact');
     }
     const payload = parsePayload(await readStdin());
     (0, runtimeEnv_1.loadRuntimeEnv)({
@@ -426,24 +493,43 @@ async function main() {
     const iranti = (0, createFirstPartyIranti_1.createFirstPartyIranti)({
         connectionString: requireConnectionString(),
         llmProvider: process.env.LLM_PROVIDER,
+        sessionLedgerSource: 'claude_hook',
+        sessionLedgerHost: 'claude_code',
     });
-    const context = await buildHookAdditionalContext({
-        iranti,
-        event,
-        payload,
-    });
-    if (!context) {
-        await (0, staffEventRegistry_1.flushStaffEventEmitter)();
-        process.exit(0);
+    let context = '';
+    try {
+        context = await buildHookAdditionalContext({
+            iranti,
+            event,
+            payload,
+        });
+        if (context) {
+            emitHookContext(event, context);
+        }
+    }
+    finally {
+        await (0, staffEventRegistry_1.flushStaffEventEmitter)().catch(() => undefined);
+        await (0, client_1.disconnectDb)().catch(() => undefined);
     }
-    emitHookContext(event, context);
-    await (0, staffEventRegistry_1.flushStaffEventEmitter)();
     process.exit(0);
 }
 if (require.main === module) {
     main().catch(async (error) => {
         try {
+            (0, staffEventRegistry_1.getStaffEventEmitter)().emit({
+                staffComponent: 'Attendant',
+                actionType: 'host_failure',
+                agentId: process.env.IRANTI_CLAUDE_AGENT_ID?.trim() || 'claude_code',
+                source: 'claude_hook',
+                level: 'audit',
+                reason: error instanceof Error ? error.message : String(error),
+                metadata: {
+                    host: 'claude_code',
+                    operation: 'hook_execution',
+                },
+            });
             await (0, staffEventRegistry_1.flushStaffEventEmitter)();
+            await (0, client_1.disconnectDb)().catch(() => undefined);
         }
         catch { }
         console.error('[claude-code-memory-hook] fatal:', error instanceof Error ? error.message : String(error));

package/dist/scripts/codex-setup.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const commandInvocation_1 = require("../src/lib/commandInvocation");
+const scaffoldCloseout_1 = require("../src/lib/scaffoldCloseout");
 function parseArgs(argv) {
     const options = {
         name: 'iranti',
@@ -82,7 +83,7 @@ function printHelp() {
         '  - Use --no-workspace-file only if you explicitly want global registration without project-local MCP file updates.',
         '  - Does not store DATABASE_URL in Codex config; iranti-mcp loads project/instance env at runtime.',
         '  - Replaces any existing MCP entry with the same name.',
-        '  - Expected host pattern: call iranti_handshake at session start (or on the first user turn if startup hooks are unavailable), then call iranti_attend before each reply.',
+        '  - Expected host pattern: run iranti_handshake at session start, run iranti_attend before each reply and before/after knowledge discovery, checkpoint at natural pauses or interrupted work, and write/checkpoint confirmed findings.',
     ].join('\n'));
 }
 function run(command, args, cwd) {
@@ -164,6 +165,7 @@ function makeWorkspaceMcpServer(options, projectEnv) {
         IRANTI_PROJECT_ENV: projectEnv,
         IRANTI_MCP_DEFAULT_AGENT: options.agent,
         IRANTI_MCP_DEFAULT_SOURCE: options.source,
+        IRANTI_MCP_HOST: 'codex_cli',
     };
     if (options.provider) {
         env.LLM_PROVIDER = options.provider;
@@ -179,6 +181,7 @@ function makeVsCodeWorkspaceMcpServer(options, projectEnv) {
     const env = {
         IRANTI_MCP_DEFAULT_AGENT: options.agent,
         IRANTI_MCP_DEFAULT_SOURCE: options.source,
+        IRANTI_MCP_HOST: 'codex_vscode',
     };
     if (options.provider) {
         env.LLM_PROVIDER = options.provider;
@@ -197,6 +200,59 @@ function makeVsCodeWorkspaceMcpServer(options, projectEnv) {
         env,
     };
 }
+function buildCodexAgentsBlock() {
+    return [
+        '<!-- iranti-rules -->',
+        '# Iranti MCP Protocol',
+        '',
+        'IMPORTANT: These rules override Codex default behavior for this repo.',
+        '',
+        '## Session start',
+        '- Call `mcp__iranti__iranti_handshake` with the active task before responding to the first user message.',
+        '- If startup hooks are unavailable, do this on the first safe user turn instead of skipping it.',
+        '',
+        '## Discovery and reply ordering',
+        '- In short: call `mcp__iranti__iranti_attend` before each reply and before/after knowledge discovery.',
+        '1. Call `mcp__iranti__iranti_attend` before drafting each user-facing reply.',
+        '2. Call `mcp__iranti__iranti_attend` before using memory discovery tools such as search, query, or related reads.',
+        '3. Call `mcp__iranti__iranti_attend` again after discovery when the findings may change what should be injected, written, or checkpointed.',
+        '',
+        '## Confirmed findings',
+        '- Call `mcp__iranti__iranti_write` after confirmed durable findings such as decisions, blockers, next steps, stable constraints, validated environment details, what worked, what failed, and what remains risky.',
+        '- If the work is still in progress, pair those writes with `mcp__iranti__iranti_checkpoint` so another session can resume cleanly.',
+        '',
+        '## Checkpoint discipline',
+        '- Call `mcp__iranti__iranti_checkpoint` at natural pauses, before stepping away from long work, when interrupted, and when completing a useful slice.',
+        '- When useful actions happen, record them in the checkpoint `actions` field so later sessions can see important commands, tests, searches, validations, and decisions without rerunning them blindly.',
+        '- Do not treat durable writes as a substitute for checkpoints. A checkpoint not written means the next session has to reconstruct state.',
+        '- Under-logged runs are non-compliant for this repo. When applicable, leave structured breadcrumbs for what you found, what worked, what failed, what changed, and what happens next instead of only a broad summary.',
+        '',
+        '## Host setup check',
+        '- If this block was missing at session start, rerun `iranti codex-setup` from the bound project root.',
+        '<!-- /iranti-rules -->',
+        '',
+    ].join('\n');
+}
+function writeWorkspaceAgentsFile(projectEnv) {
+    const projectPath = node_path_1.default.dirname(projectEnv);
+    const agentsFile = node_path_1.default.join(projectPath, 'AGENTS.md');
+    const irantiBlock = buildCodexAgentsBlock();
+    if (!node_fs_1.default.existsSync(agentsFile)) {
+        node_fs_1.default.writeFileSync(agentsFile, irantiBlock, 'utf8');
+        return { filePath: agentsFile, status: 'created' };
+    }
+    const existing = node_fs_1.default.readFileSync(agentsFile, 'utf8');
+    if (!existing.includes('<!-- iranti-rules -->')) {
+        node_fs_1.default.writeFileSync(agentsFile, `${existing.trimEnd()}\n\n${irantiBlock}`, 'utf8');
+        return { filePath: agentsFile, status: 'updated' };
+    }
+    const replaced = existing.replace(/<!-- iranti-rules -->[\s\S]*?<!-- \/iranti-rules -->/, irantiBlock.trim());
+    if (replaced === existing) {
+        return { filePath: agentsFile, status: 'unchanged' };
+    }
+    node_fs_1.default.writeFileSync(agentsFile, replaced, 'utf8');
+    return { filePath: agentsFile, status: 'updated' };
+}
 function writeWorkspaceMcpFile(projectEnv, options) {
     const projectPath = node_path_1.default.dirname(projectEnv);
     const mcpFile = node_path_1.default.join(projectPath, '.mcp.json');
@@ -292,7 +348,7 @@ function ensureCodexInstalled(repoRoot) {
         throw new Error('Codex CLI is not installed or not on PATH. Install Codex first, confirm `codex --version` works, then rerun `iranti codex-setup`.');
     }
 }
-function main() {
+async function main() {
     const options = parseArgs(process.argv.slice(2));
     const repoRoot = findPackageRoot(__dirname);
     const mcpScript = node_path_1.default.join(repoRoot, 'dist', 'scripts', 'iranti-mcp.js');
@@ -313,6 +369,8 @@ function main() {
         `IRANTI_MCP_DEFAULT_AGENT=${options.agent}`,
         '--env',
         `IRANTI_MCP_DEFAULT_SOURCE=${options.source}`,
+        '--env',
+        'IRANTI_MCP_HOST=codex_cli',
     ];
     const projectEnv = resolveProjectEnv(options);
     if (projectEnv) {
@@ -335,13 +393,19 @@ function main() {
         ? {
             mcp: writeWorkspaceMcpFile(workspaceProjectEnv, options),
             vscode: writeWorkspaceVsCodeMcpFile(workspaceProjectEnv, options),
+            agents: writeWorkspaceAgentsFile(workspaceProjectEnv),
         }
         : null;
     const registered = run('codex', ['mcp', 'get', options.name], repoRoot);
     console.log(registered);
     console.log('');
     console.log('Codex is now configured to use Iranti through MCP.');
-    console.log('Recommended MCP host pattern: run iranti_handshake at session start (or on the first user turn if no startup hook exists), then run iranti_attend before each reply.');
+    console.log('Required host pattern:');
+    console.log('  1. Run iranti_handshake at session start (or on the first safe user turn if startup hooks are unavailable).');
+    console.log('  2. Run iranti_attend before each reply and before/after knowledge discovery.');
+    console.log('  3. Run iranti_checkpoint at natural pauses, during interrupted work, and when completing a useful slice.');
+    console.log('  4. Include key commands, tests, validations, and decisions in checkpoint actions when they matter to later recovery.');
+    console.log('  5. Run iranti_write for confirmed durable findings, and pair ongoing work with iranti_checkpoint.');
     if (useInstalled) {
         console.log('Registration target: installed CLI (`iranti mcp`)');
         if (projectEnv) {
@@ -365,13 +429,31 @@ function main() {
     }
     if (options.writeWorkspaceFile) {
         if (workspaceFilesResult) {
+            const boundProjectEnv = workspaceProjectEnv;
             console.log(`Workspace .mcp.json: ${workspaceFilesResult.mcp.status} (${workspaceFilesResult.mcp.filePath})`);
             console.log(`Workspace .vscode/mcp.json: ${workspaceFilesResult.vscode.status} (${workspaceFilesResult.vscode.filePath})`);
+            console.log(`Workspace AGENTS.md: ${workspaceFilesResult.agents.status} (${workspaceFilesResult.agents.filePath})`);
+            const closeout = await (0, scaffoldCloseout_1.writeProjectScaffoldCloseout)({
+                tool: 'codex',
+                projectPath: node_path_1.default.dirname(boundProjectEnv),
+                projectEnvFile: boundProjectEnv,
+                files: [
+                    { path: workspaceFilesResult.mcp.filePath, status: workspaceFilesResult.mcp.status },
+                    { path: workspaceFilesResult.vscode.filePath, status: workspaceFilesResult.vscode.status },
+                    { path: workspaceFilesResult.agents.filePath, status: workspaceFilesResult.agents.status },
+                ],
+                agentId: options.agent || 'codex_code',
+            });
+            console.log(`Shared memory closeout: ${closeout.status} (${closeout.detail})`);
         }
         else {
             console.log('Workspace MCP files: unchanged (no project binding found from the current working directory)');
+            console.log('Shared memory closeout: skipped (no bound workspace project was found)');
         }
     }
 }
-main();
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});
 //# sourceMappingURL=codex-setup.js.map