@shadowforge0/aquifer-memory 1.7.0 → 1.8.0

package/schema/015-v1-evidence-items.sql

@@ -0,0 +1,92 @@
+-- Aquifer v1 retrieval-grade evidence items
+-- Requires: 001-base.sql, 007-v1-foundation.sql, 008-session-finalizations.sql
+-- Usage: replace ${schema} with actual schema name
+
+CREATE TABLE IF NOT EXISTS ${schema}.evidence_items (
+  id                         BIGSERIAL    PRIMARY KEY,
+  tenant_id                  TEXT         NOT NULL DEFAULT 'default',
+  source_kind                TEXT         NOT NULL
+                               CHECK (source_kind IN (
+                                 'session','session_summary','turn_embedding','insight',
+                                 'entity_state','evidence_item','raw_event','external'
+                               )),
+  source_ref                 TEXT         NOT NULL CHECK (btrim(source_ref) <> ''),
+  session_row_id             BIGINT       REFERENCES ${schema}.sessions(id) ON DELETE SET NULL,
+  turn_embedding_id          BIGINT       REFERENCES ${schema}.turn_embeddings(id) ON DELETE SET NULL,
+  summary_row_id             BIGINT       REFERENCES ${schema}.session_summaries(session_row_id) ON DELETE SET NULL,
+  created_by_finalization_id BIGINT       REFERENCES ${schema}.session_finalizations(id) ON DELETE SET NULL,
+  excerpt_text               TEXT         NOT NULL CHECK (btrim(excerpt_text) <> ''),
+  excerpt_hash               TEXT         NOT NULL CHECK (btrim(excerpt_hash) <> ''),
+  embedding                  vector(1024),
+  search_tsv                 TSVECTOR,
+  metadata                   JSONB        NOT NULL DEFAULT '{}'::jsonb,
+  created_at                 TIMESTAMPTZ  NOT NULL DEFAULT now()
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_evidence_items_dedupe
+  ON ${schema}.evidence_items (tenant_id, source_kind, source_ref, excerpt_hash);
+
+CREATE INDEX IF NOT EXISTS idx_evidence_items_source
+  ON ${schema}.evidence_items (tenant_id, source_kind, source_ref);
+
+CREATE INDEX IF NOT EXISTS idx_evidence_items_finalization
+  ON ${schema}.evidence_items (tenant_id, created_by_finalization_id)
+  WHERE created_by_finalization_id IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS idx_evidence_items_search_tsv
+  ON ${schema}.evidence_items USING GIN (search_tsv);
+
+CREATE INDEX IF NOT EXISTS idx_evidence_items_excerpt_trgm
+  ON ${schema}.evidence_items USING GIN (excerpt_text gin_trgm_ops);
+
+CREATE OR REPLACE FUNCTION ${schema}.evidence_items_search_tsv_update()
+RETURNS trigger
+LANGUAGE plpgsql
+AS $$
+BEGIN
+  BEGIN
+    NEW.search_tsv := to_tsvector('zhcfg', COALESCE(NEW.excerpt_text, ''));
+  EXCEPTION WHEN undefined_object OR undefined_function THEN
+    NEW.search_tsv := to_tsvector('simple', COALESCE(NEW.excerpt_text, ''));
+  END;
+  RETURN NEW;
+END;
+$$;
+
+DROP TRIGGER IF EXISTS trg_evidence_items_search_tsv
+  ON ${schema}.evidence_items;
+
+CREATE TRIGGER trg_evidence_items_search_tsv
+  BEFORE INSERT OR UPDATE OF excerpt_text
+  ON ${schema}.evidence_items
+  FOR EACH ROW
+  EXECUTE FUNCTION ${schema}.evidence_items_search_tsv_update();
+
+ALTER TABLE ${schema}.evidence_refs
+  ADD COLUMN IF NOT EXISTS evidence_item_id BIGINT;
+
+CREATE INDEX IF NOT EXISTS idx_evidence_refs_evidence_item
+  ON ${schema}.evidence_refs (tenant_id, evidence_item_id)
+  WHERE evidence_item_id IS NOT NULL;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1
+    FROM pg_constraint
+    WHERE conrelid = '${schema}.evidence_refs'::regclass
+      AND conname = 'evidence_refs_evidence_item_fk'
+  ) THEN
+    ALTER TABLE ${schema}.evidence_refs
+      ADD CONSTRAINT evidence_refs_evidence_item_fk
+      FOREIGN KEY (evidence_item_id)
+      REFERENCES ${schema}.evidence_items(id)
+      ON DELETE SET NULL;
+  END IF;
+END$$;
+
+COMMENT ON TABLE ${schema}.evidence_items IS
+  'Retrieval-grade evidence units. Unlike coarse session_summary refs, these are searchable anchors that can support individual memory_records.';
+
+COMMENT ON COLUMN ${schema}.evidence_refs.evidence_item_id IS
+  'Optional typed link to a retrieval-grade evidence item. source_kind/source_ref remain the audit-compatible source identity.';

package/schema/016-v1-evidence-ref-multi-item.sql

@@ -0,0 +1,19 @@
+-- Aquifer v1 evidence refs can point at multiple retrieval-grade evidence items
+-- Requires: 007-v1-foundation.sql, 015-v1-evidence-items.sql
+-- Usage: replace ${schema} with actual schema name
+
+DROP INDEX IF EXISTS ${schema}.idx_evidence_refs_dedupe;
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_evidence_refs_source_dedupe
+  ON ${schema}.evidence_refs (tenant_id, owner_kind, owner_id, source_kind, source_ref, relation_kind)
+  WHERE evidence_item_id IS NULL;
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_evidence_refs_evidence_item_dedupe
+  ON ${schema}.evidence_refs (tenant_id, owner_kind, owner_id, evidence_item_id, relation_kind)
+  WHERE evidence_item_id IS NOT NULL;
+
+COMMENT ON INDEX ${schema}.idx_evidence_refs_source_dedupe IS
+  'Legacy/coarse provenance dedupe for refs that do not yet point at retrieval-grade evidence_items.';
+
+COMMENT ON INDEX ${schema}.idx_evidence_refs_evidence_item_dedupe IS
+  'Allows multiple evidence_items for the same owner/source while deduping each typed evidence item link.';

package/schema/017-v1-memory-record-embeddings.sql

@@ -0,0 +1,25 @@
+-- Aquifer v1 current-memory semantic recall anchors
+-- Requires: 007-v1-foundation.sql
+-- Usage: replace ${schema} with actual schema name
+
+ALTER TABLE ${schema}.memory_records
+  ADD COLUMN IF NOT EXISTS embedding vector(1024);
+
+DO $$
+BEGIN
+  BEGIN
+    EXECUTE 'CREATE INDEX IF NOT EXISTS idx_memory_records_embedding_hnsw
+      ON ${schema}.memory_records USING hnsw (embedding vector_cosine_ops)
+      WHERE status = ''active'' AND visible_in_recall = true AND embedding IS NOT NULL';
+  EXCEPTION
+    WHEN undefined_object THEN
+      RAISE WARNING '[aquifer] pgvector HNSW operator class unavailable; memory_records semantic recall will use lexical/coarse anchors until vector index is available';
+    WHEN out_of_memory THEN
+      RAISE WARNING '[aquifer] HNSW build on memory_records.embedding ran out of memory; raise maintenance_work_mem and re-run migrate()';
+    WHEN program_limit_exceeded THEN
+      RAISE WARNING '[aquifer] HNSW build on memory_records.embedding exceeded an internal limit; inspect pgvector logs';
+  END;
+END$$;
+
+COMMENT ON COLUMN ${schema}.memory_records.embedding IS
+  'Optional current-memory embedding used by curated semantic/hybrid session_recall. Legacy summaries remain evidence anchors, not current truth.';

package/schema/018-v1-finalization-candidate-envelope.sql

@@ -0,0 +1,39 @@
+-- Aquifer v1 finalization candidate envelope
+-- Requires: 008-session-finalizations.sql, 010-v1-finalization-review.sql
+-- Usage: replace ${schema} with actual schema name
+--
+-- The candidate envelope is producer material, not serving truth. It records
+-- the structured synthesis input/output that core finalization validated before
+-- promoting active current memory.
+
+ALTER TABLE ${schema}.session_finalizations
+  ADD COLUMN IF NOT EXISTS candidate_envelope JSONB NOT NULL DEFAULT '{}'::jsonb,
+  ADD COLUMN IF NOT EXISTS candidate_envelope_hash TEXT,
+  ADD COLUMN IF NOT EXISTS candidate_envelope_version TEXT,
+  ADD COLUMN IF NOT EXISTS coverage JSONB NOT NULL DEFAULT '{}'::jsonb;
+
+COMMENT ON COLUMN ${schema}.session_finalizations.candidate_envelope IS
+  'Structured current-memory candidate envelope produced by handoff/recovery synthesis; producer material, not serving truth.';
+
+COMMENT ON COLUMN ${schema}.session_finalizations.candidate_envelope_hash IS
+  'Stable hash of the candidate envelope used for audit and replay comparison.';
+
+COMMENT ON COLUMN ${schema}.session_finalizations.candidate_envelope_version IS
+  'Version of the producer envelope contract, for example handoff_current_memory_synthesis_v1.';
+
+COMMENT ON COLUMN ${schema}.session_finalizations.coverage IS
+  'Coverage metadata for partial transcript, previous bootstrap, checkpoint, or other synthesis inputs.';
+
+CREATE INDEX IF NOT EXISTS idx_session_finalizations_candidate_envelope_hash
+  ON ${schema}.session_finalizations (tenant_id, candidate_envelope_hash)
+  WHERE candidate_envelope_hash IS NOT NULL;
+
+ALTER TABLE ${schema}.finalization_candidates
+  ADD COLUMN IF NOT EXISTS candidate_hash TEXT;
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_finalization_candidates_hash
+  ON ${schema}.finalization_candidates (tenant_id, finalization_id, candidate_hash)
+  WHERE candidate_hash IS NOT NULL;
+
+COMMENT ON COLUMN ${schema}.finalization_candidates.candidate_hash IS
+  'Stable per-candidate hash. candidate_index remains an ordered audit position.';

package/scripts/codex-checkpoint-commands.js

@@ -0,0 +1,464 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const codex = require('../consumers/codex');
+const {
+  acquireHeartbeatClaim,
+  checkpointCheckIntervalMs,
+  checkpointClaimDir,
+  checkpointClaimTtlMs,
+  checkpointDueFromMarker,
+  checkpointEveryMessages,
+  checkpointEveryUserMessages,
+  checkpointHeartbeatCommand,
+  checkpointHeartbeatInput,
+  checkpointMarkerDir,
+  checkpointProposalWindow,
+  checkpointSchedulerDir,
+  checkpointSpoolDir,
+  defaultHooksPath,
+  findNewestJsonlFile,
+  isoAt,
+  loadRuntimeConfig,
+  mergeCheckpointHeartbeatHook,
+  readCheckpointMarker,
+  readHooksConfig,
+  readSchedulerMarker,
+  releaseHeartbeatClaim,
+  spoolCheckpointProposal,
+  validateCheckpointTranscriptPath,
+  writeCheckpointMarker,
+  writeSchedulerMarker,
+} = require('./codex-checkpoint-runtime');
+
+function parseIntFlag(value, fallback) {
+  if (value === undefined || value === null || value === true || value === '') return fallback;
+  const parsed = parseInt(value, 10);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+function parseScopePath(value) {
+  if (!value || value === true) return undefined;
+  const parts = String(value).split(',').map(part => part.trim()).filter(Boolean);
+  return parts.length ? parts : undefined;
+}
+
+function readHookInputFromStdin() {
+  try {
+    const raw = fs.readFileSync(0, 'utf8');
+    if (!raw.trim()) return {};
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+async function cmdCheckpointPrompt(aquifer, flags, opts) {
+  const filePath = flags['file-path'];
+  if (!filePath) throw new Error('checkpoint-prompt requires --file-path');
+  const prepared = await codex.prepareActiveSessionCheckpoint(aquifer, {
+    ...opts,
+    filePath,
+    sessionId: flags['session-id'] || undefined,
+    scopeKind: flags['scope-kind'] || undefined,
+    scopeKey: flags['scope-key'] || flags['active-scope-key'] || undefined,
+    activeScopeKey: flags['active-scope-key'] || flags['scope-key'] || undefined,
+    activeScopePath: parseScopePath(flags['active-scope-path']),
+    checkpointEveryMessages: parseIntFlag(flags['checkpoint-every-messages'], undefined),
+    checkpointEveryUserMessages: parseIntFlag(flags['checkpoint-every-user-messages'], undefined),
+    maxCheckpointBytes: parseIntFlag(flags['max-checkpoint-bytes'], undefined),
+    maxCheckpointMessages: parseIntFlag(flags['max-checkpoint-messages'], undefined),
+    maxCheckpointChars: parseIntFlag(flags['max-checkpoint-chars'], undefined),
+    maxCheckpointPromptTokens: parseIntFlag(flags['max-checkpoint-prompt-tokens'], undefined),
+    force: flags.force === true,
+  });
+  if (flags.json) {
+    console.log(JSON.stringify({
+      status: prepared.status,
+      due: prepared.due === true,
+      threshold: prepared.checkpointInput?.threshold || null,
+      coverage: prepared.checkpointInput?.coverage || null,
+      prompt: prepared.prompt || null,
+    }, null, 2));
+    return;
+  }
+  if (prepared.status !== 'needs_agent_checkpoint') {
+    const threshold = prepared.checkpointInput?.threshold;
+    if (threshold) {
+      console.log(`Checkpoint prompt unavailable: ${prepared.status} (${threshold.messageCount}/${threshold.everyMessages} messages)`);
+    } else {
+      console.log(`Checkpoint prompt unavailable: ${prepared.status}`);
+    }
+    return;
+  }
+  console.log([
+    prepared.prompt,
+    '',
+    '[AQUIFER CHECKPOINT]',
+    'Use the returned JSON as checkpoint process material for a later handoff or operator-reviewed checkpoint write.',
+  ].join('\n'));
+}
+
+async function cmdCheckpointTick(aquifer, flags, opts) {
+  const paths = codex.defaultPaths(opts);
+  const filePath = flags['file-path'] || findNewestJsonlFile(opts.sessionsDir || paths.sessionsDir);
+  if (!filePath) throw new Error('checkpoint-tick requires --file-path or a readable --sessions-dir');
+  const view = codex.materializeRecoveryTranscriptView({
+    filePath,
+    sessionId: flags['session-id'] || undefined,
+  }, {
+    ...opts,
+    tailOnMaxBudget: true,
+    maxRecoveryBytes: parseIntFlag(flags['max-checkpoint-bytes'], opts.maxRecoveryBytes),
+    maxRecoveryMessages: parseIntFlag(flags['max-checkpoint-messages'], opts.maxRecoveryMessages),
+    maxRecoveryChars: parseIntFlag(flags['max-checkpoint-chars'], opts.maxRecoveryChars),
+    maxRecoveryPromptTokens: parseIntFlag(flags['max-checkpoint-prompt-tokens'], opts.maxRecoveryPromptTokens),
+  });
+  if (!view || view.status !== 'ok') {
+    const result = {
+      status: view?.status || 'missing_view',
+      due: false,
+      filePath,
+      reason: view?.reason || null,
+      view,
+    };
+    if (flags.json) console.log(JSON.stringify(result, null, 2));
+    else console.log(`Checkpoint tick unavailable: ${result.status}${result.reason ? ` (${result.reason})` : ''}`);
+    return result;
+  }
+
+  const markerDir = checkpointMarkerDir(flags, opts);
+  const marker = readCheckpointMarker(markerDir, view.sessionId);
+  const threshold = checkpointDueFromMarker(view, marker, flags);
+  if (!threshold.due) {
+    const result = {
+      status: 'not_ready',
+      due: false,
+      filePath,
+      sessionId: view.sessionId,
+      marker: marker ? {
+        markerPath: marker.markerPath,
+        messageCount: marker.messageCount || 0,
+        userCount: marker.userCount || 0,
+        writtenAt: marker.writtenAt || null,
+      } : null,
+      threshold,
+    };
+    if (flags.json) console.log(JSON.stringify(result, null, 2));
+    else {
+      console.log(`Checkpoint tick not ready: ${threshold.deltaMessages}/${threshold.everyMessages} new messages`);
+    }
+    return result;
+  }
+
+  const prepared = await codex.prepareActiveSessionCheckpoint(aquifer, {
+    ...opts,
+    filePath,
+    view,
+    sessionId: flags['session-id'] || undefined,
+    scopeKind: flags['scope-kind'] || undefined,
+    scopeKey: flags['scope-key'] || flags['active-scope-key'] || undefined,
+    activeScopeKey: flags['active-scope-key'] || flags['scope-key'] || undefined,
+    activeScopePath: parseScopePath(flags['active-scope-path']),
+    checkpointEveryMessages: parseIntFlag(flags['checkpoint-every-messages'], undefined),
+    checkpointEveryUserMessages: parseIntFlag(flags['checkpoint-every-user-messages'], undefined),
+    maxCheckpointBytes: parseIntFlag(flags['max-checkpoint-bytes'], undefined),
+    maxCheckpointMessages: parseIntFlag(flags['max-checkpoint-messages'], undefined),
+    maxCheckpointChars: parseIntFlag(flags['max-checkpoint-chars'], undefined),
+    maxCheckpointPromptTokens: parseIntFlag(flags['max-checkpoint-prompt-tokens'], undefined),
+    force: true,
+    triggerKind: marker ? 'message_count_delta' : 'message_count',
+  });
+  const writtenMarker = prepared.status === 'needs_agent_checkpoint' && flags['dry-run'] !== true
+    ? writeCheckpointMarker(markerDir, prepared)
+    : null;
+  const result = {
+    status: prepared.status,
+    due: prepared.due === true,
+    filePath,
+    sessionId: view.sessionId,
+    marker: writtenMarker,
+    previousMarker: marker ? {
+      markerPath: marker.markerPath,
+      messageCount: marker.messageCount || 0,
+      userCount: marker.userCount || 0,
+      writtenAt: marker.writtenAt || null,
+    } : null,
+    threshold,
+    coverage: prepared.checkpointInput?.coverage || null,
+    prompt: prepared.prompt || null,
+  };
+  if (flags.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return result;
+  }
+  if (prepared.status !== 'needs_agent_checkpoint') {
+    console.log(`Checkpoint tick unavailable: ${prepared.status}`);
+    return result;
+  }
+  console.log([
+    prepared.prompt,
+    '',
+    '[AQUIFER CHECKPOINT TICK]',
+    writtenMarker
+      ? `Marker written: ${writtenMarker.markerPath}`
+      : 'Dry run: marker not written.',
+    'Use the returned JSON as checkpoint process material for a later handoff or operator-reviewed checkpoint write.',
+  ].join('\n'));
+  return result;
+}
+
+function emitCheckpointHeartbeatResult(result, flags = {}) {
+  if (flags.json) console.log(JSON.stringify(result, null, 2));
+}
+
+async function cmdCheckpointHeartbeat(aquifer, flags, opts, hookInputArg) {
+  const hookInput = hookInputArg || (flags['hook-stdin'] === true ? readHookInputFromStdin() : {});
+  const input = checkpointHeartbeatInput(flags, hookInput);
+  const config = loadRuntimeConfig(flags, opts);
+  const nowMs = Date.now();
+  const intervalMs = checkpointCheckIntervalMs(flags, config);
+  const schedulerDir = checkpointSchedulerDir(flags, opts);
+
+  let safeSessionId;
+  try {
+    safeSessionId = codex.assertSafeSessionId(input.sessionId, 'sessionId');
+  } catch {
+    const result = { status: 'missing_or_invalid_session_id', due: false };
+    emitCheckpointHeartbeatResult(result, flags);
+    return result;
+  }
+
+  const marker = readSchedulerMarker(schedulerDir, safeSessionId);
+  const proposalWindow = checkpointProposalWindow(marker, intervalMs, nowMs);
+  const nextCheckAt = proposalWindow.nextProposalAt || null;
+  if (flags.force !== true && !proposalWindow.due) {
+    const result = {
+      status: 'not_due_time',
+      due: false,
+      sessionId: safeSessionId,
+      lastProposalAt: proposalWindow.lastProposalAt,
+      nextCheckAt: proposalWindow.nextProposalAt,
+      markerPath: marker.markerPath,
+    };
+    emitCheckpointHeartbeatResult(result, flags);
+    return result;
+  }
+
+  const claim = acquireHeartbeatClaim(
+    checkpointClaimDir(flags, opts),
+    safeSessionId,
+    nowMs,
+    checkpointClaimTtlMs(flags, config),
+  );
+  if (!claim.acquired) {
+    const result = {
+      status: 'checkpoint_heartbeat_claimed',
+      due: false,
+      sessionId: safeSessionId,
+      reason: claim.reason || 'claim_active',
+    };
+    emitCheckpointHeartbeatResult(result, flags);
+    return result;
+  }
+
+  try {
+    const pathCheck = validateCheckpointTranscriptPath(input.filePath, opts);
+    if (!pathCheck.ok) {
+      const written = writeSchedulerMarker(schedulerDir, safeSessionId, {
+        lastCheckAt: isoAt(nowMs),
+        nextCheckAt,
+        lastStatus: pathCheck.status,
+        lastReason: pathCheck.reason || null,
+        hookEventName: input.hookEventName || null,
+      });
+      const result = {
+        status: pathCheck.status,
+        due: false,
+        sessionId: safeSessionId,
+        reason: pathCheck.reason || null,
+        nextCheckAt,
+        markerPath: written?.markerPath || null,
+      };
+      emitCheckpointHeartbeatResult(result, flags);
+      return result;
+    }
+
+    const view = codex.materializeRecoveryTranscriptView({
+      filePath: pathCheck.filePath,
+      sessionId: safeSessionId,
+    }, {
+      ...opts,
+      tailOnMaxBudget: true,
+      maxRecoveryBytes: parseIntFlag(flags['max-checkpoint-bytes'], opts.maxRecoveryBytes),
+      maxRecoveryMessages: parseIntFlag(flags['max-checkpoint-messages'], opts.maxRecoveryMessages),
+      maxRecoveryChars: parseIntFlag(flags['max-checkpoint-chars'], opts.maxRecoveryChars),
+      maxRecoveryPromptTokens: parseIntFlag(flags['max-checkpoint-prompt-tokens'], opts.maxRecoveryPromptTokens),
+    });
+    if (!view || view.status !== 'ok') {
+      const written = writeSchedulerMarker(schedulerDir, safeSessionId, {
+        lastCheckAt: isoAt(nowMs),
+        nextCheckAt,
+        lastStatus: view?.status || 'missing_view',
+        lastReason: view?.reason || null,
+        hookEventName: input.hookEventName || null,
+      });
+      const result = {
+        status: view?.status || 'missing_view',
+        due: false,
+        sessionId: safeSessionId,
+        reason: view?.reason || null,
+        nextCheckAt,
+        markerPath: written?.markerPath || null,
+      };
+      emitCheckpointHeartbeatResult(result, flags);
+      return result;
+    }
+
+    const coveredMessages = Number(marker?.lastCoveredMessageCount || 0);
+    const coveredUsers = Number(marker?.lastCoveredUserCount || 0);
+    const threshold = checkpointDueFromMarker(view, coveredMessages > 0 || coveredUsers > 0
+      ? { messageCount: coveredMessages, userCount: coveredUsers }
+      : null, flags, config);
+    if (!threshold.due) {
+      const written = writeSchedulerMarker(schedulerDir, safeSessionId, {
+        lastCheckAt: isoAt(nowMs),
+        nextCheckAt,
+        lastStatus: 'not_enough_messages',
+        lastReason: null,
+        hookEventName: input.hookEventName || null,
+        lastObservedMessageCount: threshold.messageCount,
+        lastObservedUserCount: threshold.userCount,
+      });
+      const result = {
+        status: 'not_enough_messages',
+        due: false,
+        sessionId: safeSessionId,
+        nextCheckAt,
+        markerPath: written?.markerPath || null,
+        threshold,
+      };
+      emitCheckpointHeartbeatResult(result, flags);
+      return result;
+    }
+
+    const prepared = await codex.prepareActiveSessionCheckpoint(aquifer, {
+      ...opts,
+      filePath: pathCheck.filePath,
+      view,
+      sessionId: safeSessionId,
+      scopeKind: flags['scope-kind'] || undefined,
+      scopeKey: flags['scope-key'] || flags['active-scope-key'] || undefined,
+      activeScopeKey: flags['active-scope-key'] || flags['scope-key'] || undefined,
+      activeScopePath: parseScopePath(flags['active-scope-path']),
+      checkpointEveryMessages: checkpointEveryMessages(flags, config),
+      checkpointEveryUserMessages: checkpointEveryUserMessages(flags, config),
+      force: true,
+      includeCurrentMemory: false,
+      triggerKind: 'heartbeat_time_window',
+    });
+    if (prepared.status !== 'needs_agent_checkpoint') {
+      const written = writeSchedulerMarker(schedulerDir, safeSessionId, {
+        lastCheckAt: isoAt(nowMs),
+        nextCheckAt,
+        lastStatus: prepared.status,
+        hookEventName: input.hookEventName || null,
+      });
+      const result = {
+        status: prepared.status,
+        due: false,
+        sessionId: safeSessionId,
+        nextCheckAt,
+        markerPath: written?.markerPath || null,
+      };
+      emitCheckpointHeartbeatResult(result, flags);
+      return result;
+    }
+
+    const spool = flags['dry-run'] === true
+      ? null
+      : spoolCheckpointProposal(checkpointSpoolDir(flags, opts), prepared, {
+        sessionId: safeSessionId,
+        source: opts.source || 'codex',
+        hookEventName: input.hookEventName || null,
+      });
+    const proposalAt = isoAt(nowMs);
+    const nextProposalAt = isoAt(nowMs + intervalMs);
+    const markerPatch = {
+      lastCheckAt: proposalAt,
+      lastProposalAt: flags['dry-run'] === true ? marker?.lastProposalAt || null : proposalAt,
+      nextCheckAt: flags['dry-run'] === true ? nextCheckAt : nextProposalAt,
+      lastStatus: flags['dry-run'] === true ? 'checkpoint_due_dry_run' : 'checkpoint_spooled',
+      lastReason: null,
+      hookEventName: input.hookEventName || null,
+      lastSpoolPath: spool?.filePath || marker?.lastSpoolPath || null,
+    };
+    if (flags['dry-run'] !== true) {
+      markerPatch.lastCoveredMessageCount = threshold.messageCount;
+      markerPatch.lastCoveredUserCount = threshold.userCount;
+    }
+    const written = writeSchedulerMarker(schedulerDir, safeSessionId, markerPatch);
+    const result = {
+      status: flags['dry-run'] === true ? 'checkpoint_due_dry_run' : 'checkpoint_spooled',
+      due: true,
+      sessionId: safeSessionId,
+      nextCheckAt: flags['dry-run'] === true ? nextCheckAt : nextProposalAt,
+      markerPath: written?.markerPath || null,
+      spool,
+      threshold,
+      coverage: prepared.checkpointInput?.coverage || null,
+    };
+    emitCheckpointHeartbeatResult(result, flags);
+    return result;
+  } finally {
+    releaseHeartbeatClaim(claim);
+  }
+}
+
+async function cmdCheckpointHeartbeatHook(flags, opts) {
+  if (!flags['scope-key'] && !flags['active-scope-key']) {
+    throw new Error('checkpoint-heartbeat-hook requires --scope-key or --active-scope-key');
+  }
+  const hooksPath = flags['hooks-path'] || defaultHooksPath(opts);
+  const before = readHooksConfig(hooksPath);
+  const after = mergeCheckpointHeartbeatHook(before, flags, opts);
+  const changed = JSON.stringify(before) !== JSON.stringify(after);
+  const apply = flags.apply === true;
+  if (apply) {
+    fs.mkdirSync(path.dirname(hooksPath), { recursive: true });
+    fs.writeFileSync(hooksPath, JSON.stringify(after, null, 2) + '\n', 'utf8');
+  }
+  const result = {
+    status: apply ? 'applied' : 'dry_run',
+    hooksPath,
+    changed,
+    event: 'UserPromptSubmit',
+    command: checkpointHeartbeatCommand(flags, opts),
+    hooks: after,
+  };
+  if (flags.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return result;
+  }
+  console.log([
+    `Codex heartbeat hook ${apply ? 'applied' : 'dry run'}: ${hooksPath}`,
+    `Changed: ${changed ? 'yes' : 'no'}`,
+    'Command:',
+    result.command,
+    apply ? '' : 'Pass --apply to write the merged hooks.json.',
+  ].filter(Boolean).join('\n'));
+  return result;
+}
+
+module.exports = {
+  cmdCheckpointHeartbeat,
+  cmdCheckpointHeartbeatHook,
+  cmdCheckpointPrompt,
+  cmdCheckpointTick,
+  emitCheckpointHeartbeatResult,
+  parseScopePath,
+  readHookInputFromStdin,
+};