@joenandez/academy 0.4.0 → 0.5.12

package/hooks/memory_bridge.mjs

@@ -1,13 +1,25 @@
-import { appendFileSync, existsSync, readFileSync } from 'node:fs';
+import {
+  accessSync,
+  appendFileSync,
+  constants,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+} from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { withFileLock } from './hook_runtime.mjs';
 
 /**
  * Academy names no specific client except in this module. The memory sync
  * bridge stays client-specific by explicit decision, so every client-named
  * identifier Academy needs — env keys, tool permission, skill guidance, and the
  * observation copy itself — lives here. Client-neutral layers import these
- * declarations and inject them only behind ACADEMY_MEMORY_BRIDGE.
+ * declarations and inject them on every agent. The bridge is always on; it
+ * copies nothing unless the client's own keys and observations directory exist.
+ * The module also holds the Backstory source: observations of recorded
+ * sessions, found by session id under the Backstory home.
  */
 export const MEMORY_BRIDGE_ENV = {
   enabled: 'GROVE_MEMORY_ENABLED',
@@ -34,48 +46,145 @@ optional. Skip this section when \`subspace-memory\` is not installed.
 Subspace memory may enrich or corroborate an eligible run. It can never
 establish eligibility.`;
 
-function formatDate(date) {
-  return date.toISOString().slice(0, 10);
+// The Subspace wrapper is the only reader of grove.db. Academy hands it a
+// workspace path and lets it resolve GROVE_* for the child, exactly as tldr's
+// subspace_memory_launch.mjs does for scheduled jobs.
+const MEMORY_WRAPPER = join('bin', 'helm-job-memory-wrapper');
+const CLAUDE_SETTINGS_FILE = 'claude-code-subspace-settings.json';
+const PANE_ENV_KEYS = ['GROVE_PANE_ID', 'SUBSPACE_PANE_ID'];
+
+/** True when the client already resolved this process's memory workspace. */
+export function bridgeEnvPresent(env) {
+  return Boolean(env[MEMORY_BRIDGE_ENV.project] && env[MEMORY_BRIDGE_ENV.workspace]);
+}
+
+function bridgeHome(env) {
+  const explicit = String(env[MEMORY_BRIDGE_ENV.home] ?? '').trim();
+  return explicit || join(env.HOME || homedir(), '.subspace');
 }
 
-function syncDates() {
-  const today = new Date();
-  const yesterday = new Date(today);
-  yesterday.setDate(today.getDate() - 1);
-  return [formatDate(today), formatDate(yesterday)];
+function isExecutable(path) {
+  try {
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The installed wrapper, or null when this machine has none. */
+export function bridgeLauncher(env) {
+  const home = bridgeHome(env);
+  const wrapper = join(home, MEMORY_WRAPPER);
+  return isExecutable(wrapper) ? { home, wrapper } : null;
+}
+
+// The memory Stop hook ships async; a one-shot run exits before an async hook
+// writes, so it is forced synchronous (same transform as tldr).
+function isAsyncMemoryStopHook(hook) {
+  const command = typeof hook?.command === 'string' ? hook.command : '';
+  return (
+    hook?.async === true &&
+    command.includes('subspace-memory') &&
+    command.includes('stop-lifecycle')
+  );
+}
+
+function effectiveClaudeSettings(path) {
+  try {
+    const settings = JSON.parse(readFileSync(path, 'utf8'));
+    const hooks = (settings?.hooks?.Stop || []).flatMap((group) => group?.hooks || []);
+    const asyncHooks = hooks.filter(isAsyncMemoryStopHook);
+    for (const hook of asyncHooks) hook.async = false;
+    return asyncHooks.length > 0 ? JSON.stringify(settings) : path;
+  } catch {
+    return path;
+  }
+}
+
+/** Claude arguments that load the client's settings, or none when absent. */
+export function bridgeClaudeSettingsArgs(launcher) {
+  const path = join(launcher.home, CLAUDE_SETTINGS_FILE);
+  if (!existsSync(path)) return [];
+  return ['--settings', effectiveClaudeSettings(path)];
+}
+
+const USER_MEMORY_HOOK = /subspace-memory|subspace-hooks\/|subspace-claude-/;
+
+function userClaudeSettingsPaths(env) {
+  const paths = [join(env.HOME || homedir(), '.claude', 'settings.json')];
+  if (env.CLAUDE_CONFIG_DIR) paths.push(join(env.CLAUDE_CONFIG_DIR, 'settings.json'));
+  return paths;
+}
+
+function runsMemoryHooks(path) {
+  try {
+    const groups = Object.values(JSON.parse(readFileSync(path, 'utf8'))?.hooks ?? {}).flat();
+    return groups
+      .flatMap((group) => group?.hooks || [])
+      .some((hook) => USER_MEMORY_HOOK.test(String(hook?.command ?? '')));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * True when the user's own Claude settings already run the client's memory
+ * hooks. Claude Code merges settings and de-duplicates hooks only on identical
+ * command text, so loading the client's settings file too would fire every
+ * memory hook twice.
+ */
+export function bridgeHooksInUserSettings(env) {
+  return userClaudeSettingsPaths(env).some(runsMemoryHooks);
+}
+
+/** The wrapped argv and env that start `command` with a memory workspace. */
+export function bridgeLaunch(launcher, { command, args, env, workspaceCwd }) {
+  const unsetPane = PANE_ENV_KEYS.flatMap((key) => ['-u', key]);
+  return {
+    command: launcher.wrapper,
+    args: ['/usr/bin/env', ...unsetPane, command, ...args],
+    env: {
+      ...env,
+      [MEMORY_BRIDGE_ENV.home]: launcher.home,
+      PATH: `${join(launcher.home, 'bin')}:${env.PATH || ''}`,
+      [MEMORY_BRIDGE_ENV.enabled]: '1',
+      HELM_MEMORY_CONTEXT: JSON.stringify({ workspace_cwd: workspaceCwd }),
+    },
+  };
+}
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+function sweepDates(days) {
+  const now = Date.now();
+  return Array.from({ length: days }, (_, back) =>
+    new Date(now - back * DAY_MS).toISOString().slice(0, 10),
+  );
 }
 
 function memoryKey(entry) {
   return `${entry.sessionId || ''}|${entry.timestamp || ''}|${entry.turnNumber || ''}`;
 }
 
-function readExistingKeys(path) {
-  const keys = new Set();
-  if (!existsSync(path)) return keys;
+// Each parsed row keeps its source line, so a copy is byte-for-byte.
+function readJsonlLines(path) {
+  if (!existsSync(path)) return [];
+  const rows = [];
   for (const line of readFileSync(path, 'utf8').split('\n')) {
     const trimmed = line.trim();
     if (!trimmed) continue;
     try {
-      keys.add(memoryKey(JSON.parse(trimmed)));
+      rows.push({ entry: JSON.parse(trimmed), line: trimmed });
     } catch {
-      // Ignore malformed archive lines.
+      // Ignore malformed lines.
     }
   }
-  return keys;
+  return rows;
 }
 
-function subspaceObservationsDir(env) {
-  const project = env[MEMORY_BRIDGE_ENV.project];
-  const workspace = env[MEMORY_BRIDGE_ENV.workspace];
-  if (!project || !workspace) return null;
-  const roots = [env[MEMORY_BRIDGE_ENV.home], join(env.HOME || homedir(), '.subspace')].filter(
-    Boolean,
-  );
-  for (const root of roots) {
-    const dir = join(root, project, workspace, 'memory', 'observations');
-    if (existsSync(dir)) return dir;
-  }
-  return null;
+function readJsonl(path) {
+  return readJsonlLines(path).map(({ entry }) => entry);
 }
 
 function memorySyncEnabled(env) {
@@ -83,38 +192,163 @@ function memorySyncEnabled(env) {
   return enabled === '1' || enabled === 'true';
 }
 
-function syncObservationFile(subspaceFile, agentFile, sessionId) {
-  const existingKeys = readExistingKeys(agentFile);
-  let synced = 0;
-  for (const line of readFileSync(subspaceFile, 'utf8').split('\n')) {
-    const trimmed = line.trim();
-    if (!trimmed) continue;
+/**
+ * The memory location a session record keeps, so a later sweep reads that
+ * session's own observation folder. A nightly session records none: its own
+ * turns must never become the next nightly's input.
+ */
+export function bridgeSessionFields(env) {
+  if (!memorySyncEnabled(env) || !bridgeEnvPresent(env)) return {};
+  if (env.ACADEMY_NIGHTLY_RUN === '1') return {};
+  return {
+    groveProject: env[MEMORY_BRIDGE_ENV.project],
+    groveWorkspace: env[MEMORY_BRIDGE_ENV.workspace],
+  };
+}
+
+function recordedSessionsByWorkspace(agentDir) {
+  const groups = new Map();
+  for (const row of readJsonl(join(agentDir, 'memory', 'sessions.jsonl'))) {
+    if (!row.sessionId || !row.groveProject || !row.groveWorkspace) continue;
+    const key = JSON.stringify([row.groveProject, row.groveWorkspace]);
+    if (!groups.has(key)) {
+      groups.set(key, {
+        project: row.groveProject,
+        workspace: row.groveWorkspace,
+        sessionIds: new Set(),
+      });
+    }
+    groups.get(key).sessionIds.add(row.sessionId);
+  }
+  return [...groups.values()];
+}
+
+// SUBSPACE_HOME first, then ~/.subspace, per date file: a home can hold an
+// older copy of a workspace folder while today's file lives in the other.
+function observationFile(env, group, date) {
+  const roots = [env[MEMORY_BRIDGE_ENV.home], join(env.HOME || homedir(), '.subspace')];
+  return roots
+    .filter(Boolean)
+    .map((root) => join(root, group.project, group.workspace, 'memory', 'observations'))
+    .map((dir) => join(dir, `${date}.jsonl`))
+    .find((path) => existsSync(path));
+}
+
+// shortcut: scans every Backstory context for the date, upgrade if Backstory is installed widely.
+function backstoryObservationFiles(env, date) {
+  const projects = join(
+    env.BACKSTORY_HOME || join(env.HOME || homedir(), '.backstory'),
+    'projects',
+  );
+  const dirs = (path) => {
     try {
-      const entry = JSON.parse(trimmed);
-      const key = memoryKey(entry);
-      if (entry.sessionId !== sessionId || existingKeys.has(key)) continue;
-      appendFileSync(agentFile, `${trimmed}\n`);
-      existingKeys.add(key);
-      synced++;
+      return readdirSync(path);
     } catch {
-      // Ignore malformed Subspace observation lines.
+      return [];
+    }
+  };
+  return dirs(projects)
+    .flatMap((project) =>
+      dirs(join(projects, project, 'contexts')).map((context) =>
+        join(projects, project, 'contexts', context, 'memory', 'observations', `${date}.jsonl`),
+      ),
+    )
+    .filter((path) => existsSync(path));
+}
+
+// Nightly sessions are excluded: their own turns must not feed the next nightly.
+function backstorySessionIds(agentDir) {
+  return new Set(
+    readJsonl(join(agentDir, 'memory', 'sessions.jsonl'))
+      .filter((row) => row.sessionId && !row.nightly)
+      .map((row) => row.sessionId),
+  );
+}
+
+function sweepBackstory(archiveDir, sessionIds, days, env) {
+  let copied = 0;
+  for (const date of sweepDates(days)) {
+    for (const source of backstoryObservationFiles(env, date)) {
+      copied += copySessionObservations(source, join(archiveDir, `${date}.jsonl`), sessionIds);
     }
   }
-  return synced;
+  return copied;
+}
+
+function copySessionObservations(sourceFile, agentFile, sessionIds) {
+  const existingKeys = new Set(readJsonl(agentFile).map(memoryKey));
+  let copied = 0;
+  for (const { entry, line } of readJsonlLines(sourceFile)) {
+    const key = memoryKey(entry);
+    if (!sessionIds.has(entry.sessionId) || existingKeys.has(key)) continue;
+    appendFileSync(agentFile, `${line}\n`);
+    existingKeys.add(key);
+    copied++;
+  }
+  return copied;
 }
 
 /**
- * Copy the client's observations for this session into the agent's own archive.
- * The client-neutral hook calls this and learns only a count.
+ * Copy observations the client wrote for any session recorded for this agent,
+ * from each session's own workspace folder, into the agent's own archive. The
+ * client writes observations after Stop, so every sweep catches what earlier
+ * ones could not yet see; `memoryKey` keeps a repeated sweep from duplicating.
+ * The client-neutral callers learn only a count.
  */
-export function syncBridgeObservations(env, observationsDir, sessionId) {
-  const subspaceDir = subspaceObservationsDir(env);
-  if (!subspaceDir || !memorySyncEnabled(env)) return 0;
-  let synced = 0;
-  for (const date of syncDates()) {
-    const subspaceFile = join(subspaceDir, `${date}.jsonl`);
-    if (!existsSync(subspaceFile)) continue;
-    synced += syncObservationFile(subspaceFile, join(observationsDir, `${date}.jsonl`), sessionId);
+export function sweepBridgeObservations(agentDir, { days = 2, env = process.env } = {}) {
+  try {
+    return sweepRecordedSessions(agentDir, days, env);
+  } catch (error) {
+    // A failed sweep must not cost the caller its own work; the next sweep
+    // covers the same window.
+    process.stderr.write(
+      `${JSON.stringify({ event: 'memory.sweep_failed', params: { agentDir, days }, error: error.stack })}\n`,
+    );
+    return 0;
   }
-  return synced;
+}
+
+function sweepRecordedSessions(agentDir, days, env) {
+  const groups = recordedSessionsByWorkspace(agentDir);
+  const archiveDir = join(agentDir, 'memory', 'observations');
+  mkdirSync(archiveDir, { recursive: true });
+  return withFileLock(join(agentDir, 'memory', 'sweep.lock'), () => {
+    let copied = 0;
+    for (const group of groups) {
+      for (const date of sweepDates(days)) {
+        const source = observationFile(env, group, date);
+        if (!source) continue;
+        const target = join(archiveDir, `${date}.jsonl`);
+        copied += copySessionObservations(source, target, group.sessionIds);
+      }
+    }
+    return copied + sweepBackstory(archiveDir, backstorySessionIds(agentDir), days, env);
+  });
+}
+
+// --- Curator feed: the client facts scripts/cli/curator-feed*.mjs reads ---
+
+/** The Codex originator the client stamps on sessions it starts for the user. */
+export const MEMORY_BRIDGE_CODEX_ORIGINATOR = 'subspace';
+
+/** Every client home the feed reads, in order: SUBSPACE_HOME, ~/.subspace-alpha, ~/.subspace. */
+export function bridgeHomes(env) {
+  const home = env.HOME || homedir();
+  const homes = [
+    env[MEMORY_BRIDGE_ENV.home],
+    join(home, '.subspace-alpha'),
+    join(home, '.subspace'),
+  ];
+  return [...new Set(homes.filter(Boolean))];
+}
+
+/** The client project and workspace a cwd sits in, or null outside a client home. */
+export function bridgeWorkspaceOf(cwd) {
+  const m = /\.subspace(?:-alpha)?\/([^/]+)\/([^/]+)/.exec(cwd ?? '');
+  return m ? { project: m[1], workspace: m[2] } : null;
+}
+
+/** A prompt without the context blocks the client injects into it. */
+export function stripBridgeContext(text) {
+  return text.replace(/<(subspace|memory|rag|context)[-_a-z]*>.*?<\/\1[-_a-z]*>/gs, '');
 }

package/hooks/memory_store.mjs

@@ -8,39 +8,72 @@ import {
 } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { jsonlHasValue, resolvedAgentDir, withFileLock } from './hook_runtime.mjs';
+import { bridgeSessionFields } from './memory_bridge.mjs';
 
 // Academy's own per-agent memory state. Client-neutral: nothing here knows
-// which client, if any, feeds the observation archive.
+// which client, if any, feeds the observation archive; the bridge supplies
+// any client location a session record keeps.
 
 export function pendingMarkerPath(agentDir) {
   return join(resolve(agentDir), 'memory', 'pending-consolidation.json');
 }
 
-export function markPendingConsolidation(memoryDir) {
+// The marker's writers and the nightly's remover share one lock, so a bump
+// never lands between the remover's revision check and its unlink.
+export function withPendingMarkerLock(memoryDir, fn) {
+  return withFileLock(join(memoryDir, 'pending-consolidation.lock'), fn);
+}
+
+// `write` runs inside the lock, so a writer's input commits with its bump: the
+// nightly's remover sees both or neither. A `write` that returns false skips
+// the bump. False means the lock timed out and `write` never ran: the caller
+// wrote nothing, so a hook's idempotent sweep runs again next time and
+// `notes add` reports the failure.
+export function markPendingConsolidation(memoryDir, write = () => true) {
   const markerPath = pendingMarkerPath(resolve(memoryDir, '..'));
-  withFileLock(join(memoryDir, 'pending-consolidation.lock'), () => {
-    let revision = 0;
-    if (existsSync(markerPath)) {
-      try {
-        revision = Number(JSON.parse(readFileSync(markerPath, 'utf8')).revision) || 0;
-      } catch {
-        // Replace malformed private state with the next valid revision.
+  try {
+    withPendingMarkerLock(memoryDir, () => {
+      if (write() === false) return;
+      let revision = 0;
+      if (existsSync(markerPath)) {
+        try {
+          revision = Number(JSON.parse(readFileSync(markerPath, 'utf8')).revision) || 0;
+        } catch {
+          // Replace malformed private state with the next valid revision.
+        }
       }
-    }
-    const tempPath = join(memoryDir, `.pending-consolidation.${process.pid}.${Date.now()}.tmp`);
-    writeFileSync(
-      tempPath,
-      JSON.stringify(
-        {
-          revision: revision + 1,
-          updatedAt: new Date().toISOString(),
-        },
-        null,
-        2,
-      ) + '\n',
-    );
-    renameSync(tempPath, markerPath);
-  });
+      const tempPath = join(memoryDir, `.pending-consolidation.${process.pid}.${Date.now()}.tmp`);
+      writeFileSync(
+        tempPath,
+        JSON.stringify(
+          {
+            revision: revision + 1,
+            updatedAt: new Date().toISOString(),
+          },
+          null,
+          2,
+        ) + '\n',
+      );
+      renameSync(tempPath, markerPath);
+    });
+    return true;
+  } catch (error) {
+    if (!skippedOnLockTimeout(error, { memoryDir, write: 'pending_marker' })) throw error;
+    return false;
+  }
+}
+
+function skippedOnLockTimeout(error, params) {
+  if (error?.code !== 'lock_timeout') return false;
+  console.error(
+    JSON.stringify({
+      event: 'memory.lock_timeout',
+      params,
+      result: { written: false },
+      status: 'skipped',
+    }),
+  );
+  return true;
 }
 
 export function recordSession(memoryDir, payload, env) {
@@ -48,7 +81,7 @@ export function recordSession(memoryDir, payload, env) {
   if (!sessionId) return;
   const sessionsPath = join(memoryDir, 'sessions.jsonl');
   mkdirSync(memoryDir, { recursive: true });
-  withFileLock(join(memoryDir, 'sessions.lock'), () => {
+  const appendRow = () => {
     if (jsonlHasValue(sessionsPath, 'sessionId', sessionId)) return;
     appendFileSync(
       sessionsPath,
@@ -60,7 +93,26 @@ export function recordSession(memoryDir, payload, env) {
         cwd: payload.cwd || null,
         projectDir: env.ACADEMY_PROJECT_DIR || null,
         source: 'stop',
+        ...bridgeSessionFields(env),
+        // The Backstory source matches by session id, so it needs this marker.
+        ...(env.ACADEMY_NIGHTLY_RUN === '1' ? { nightly: true } : {}),
       }) + '\n',
     );
-  });
+  };
+  try {
+    withFileLock(join(memoryDir, 'sessions.lock'), appendRow);
+  } catch (error) {
+    if (error?.code !== 'lock_timeout') throw error;
+    // A one-turn session has no later Stop to record it, so write without the
+    // lock. The sweep groups ids in a Set, so a duplicate row is harmless.
+    console.error(
+      JSON.stringify({
+        event: 'memory.lock_timeout',
+        params: { memoryDir, write: 'session_record' },
+        result: { written: true, locked: false },
+        status: 'warn',
+      }),
+    );
+    appendRow();
+  }
 }

package/hooks/register_session.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { appendFileSync, mkdirSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import {
@@ -10,6 +10,9 @@ import {
   runtimeEnvFor,
   withFileLock,
 } from './hook_runtime.mjs';
+import { measureSessionContext } from './context_metrics.mjs';
+import { bridgeSessionFields, sweepBridgeObservations } from './memory_bridge.mjs';
+import { markPendingConsolidation } from './memory_store.mjs';
 
 function appendSession(sessionsPath, session) {
   if (jsonlHasValue(sessionsPath, 'sessionId', session.sessionId)) return true;
@@ -27,25 +30,84 @@ export function registerAcademySession(payload, env = process.env) {
   // unattributable rather than corrupt, so it is written without the field and
   // counted by `doctor`.
   const agentDir = resolvedAgentDir(env.ACADEMY_AGENT_DIR);
+  const recorded = writeIndexRow(env, {
+    sessionId,
+    agentName,
+    ...(agentDir ? { agentDir } : {}),
+    cwd,
+    startedAt: new Date().toISOString(),
+    ...(payload.transcript_path ? { transcriptPath: payload.transcript_path } : {}),
+    ...contextField(agentDir),
+    ...bridgeSessionFields(env),
+  });
+  sweepEarlierSessions(agentDir, env);
+  return recorded;
+}
 
+// shortcut: reads the prompt file after launch, so two near-simultaneous launches of the same agent can read each other's render; upgrade by passing the measurement through the launch env.
+function contextField(agentDir) {
+  if (!agentDir) return {};
   try {
-    const academyDir = join(env.HOME || homedir(), '.academy');
-    const sessionsPath = join(academyDir, 'sessions.jsonl');
-    mkdirSync(academyDir, { recursive: true });
-    return withFileLock(join(academyDir, 'sessions.lock'), () =>
-      appendSession(sessionsPath, {
-        sessionId,
-        agentName,
-        ...(agentDir ? { agentDir } : {}),
-        cwd,
-        startedAt: new Date().toISOString(),
+    const context = measureSessionContext(agentDir);
+    return context ? { context } : {};
+  } catch (err) {
+    console.error(
+      JSON.stringify({
+        event: 'session.context_measure_failed',
+        params: { agentDir },
+        result: { error: err.message },
+        status: 'failed',
       }),
     );
-  } catch {
-    return false;
+    return {};
   }
 }
 
+function logHookFailure(event, params, error, status = 'failed') {
+  console.error(
+    JSON.stringify({ event, params, result: { error: error.message }, status, stack: error.stack }),
+  );
+}
+
+// An unlocked append can duplicate a row only if the lock holder writes this
+// same session id at once; appendSession still checks for it first.
+function writeIndexRow(env, row) {
+  const academyDir = join(env.HOME || homedir(), '.academy');
+  const sessionsPath = join(academyDir, 'sessions.jsonl');
+  try {
+    mkdirSync(academyDir, { recursive: true });
+    return withFileLock(join(academyDir, 'sessions.lock'), () => appendSession(sessionsPath, row));
+  } catch (error) {
+    if (error?.code !== 'lock_timeout') {
+      logHookFailure('session.index_write_failed', { academyDir }, error);
+      return false;
+    }
+    logHookFailure('session.lock_timeout', { academyDir, write: 'session_index' }, error, 'warn');
+    try {
+      return appendSession(sessionsPath, row);
+    } catch (writeError) {
+      logHookFailure('session.index_write_failed', { academyDir }, writeError);
+      return false;
+    }
+  }
+}
+
+// A new session picks up the last turn of the session before it, which the
+// client wrote after that session's final Stop had already swept.
+// The copies commit with the marker bump; no memory/ means nothing to sweep.
+function sweepEarlierSessions(agentDir, env) {
+  if (!agentDir || !existsSync(join(agentDir, 'memory'))) return;
+  markPendingConsolidation(
+    join(agentDir, 'memory'),
+    () => sweepBridgeObservations(agentDir, { env }) > 0,
+  );
+}
+
 if (isMainModule(import.meta.url)) {
-  registerAcademySession(readPayload());
+  try {
+    registerAcademySession(readPayload());
+  } catch (error) {
+    // A hook must never fail the session it observes.
+    logHookFailure('session.register_failed', {}, error);
+  }
 }

package/hooks/roque/.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "roque",
+  "version": "0.1.1+54ca4d5",
+  "description": "Keeps long Claude Code and Codex sessions on track across native compaction with a per-session state file.",
+  "hooks": "./hooks.json"
+}

package/hooks/roque/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joe Fernandez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/hooks/roque/SOURCE

@@ -0,0 +1 @@
+54ca4d587b911adee6f71ce6239d448359a10843