@damiangilgonzalez/harness 1.3.7

package/targets/hook-once.mjs

@@ -0,0 +1,123 @@
+// hook-once.mjs — cross-scope single-shot guard for rsc hooks.
+//
+// rsc can be wired in more than one scope at once (user-level ~/.claude/settings.json AND
+// project-level .claude/settings.json). Each scope runs its OWN copy of the hook scripts, so
+// the same always-on body and the same SDD gate get injected twice — once per scope. wireHook()
+// is idempotent within a settings file but blind to the other one, so the duplication cannot be
+// solved at install time; it has to be solved at injection time.
+//
+// The marker therefore CANNOT live in `.rsc/` — each scope has its own root, which is the whole
+// problem. It lives in a per-user directory under the OS temp dir, which both scopes can see.
+//
+// Claude Code gives every hook the same `session_id` for both scopes, and the same `prompt_id`
+// within one turn (docs: code.claude.com/docs/en/hooks). That is the dedup key.
+//
+// Fail-open is the rule throughout: if anything about this mechanism misbehaves, the hook prints.
+// A duplicated block costs context; a swallowed always-on layer costs the session its behaviour.
+import { mkdirSync, writeFileSync, statSync, readdirSync, unlinkSync, utimesSync, readFileSync } from 'node:fs';
+import { tmpdir, userInfo } from 'node:os';
+import { join } from 'node:path';
+
+const PRUNE_AFTER_MS = 24 * 3600 * 1000;
+
+// Per-user so two accounts on one machine never share (or suppress) each other's markers.
+// RSC_HOOK_MARKER_DIR overrides it so tests get an isolated directory per case.
+export function markerDir() {
+  if (process.env.RSC_HOOK_MARKER_DIR) {
+    const dir = process.env.RSC_HOOK_MARKER_DIR;
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    return dir;
+  }
+  let uid = 'anon';
+  try { uid = String(userInfo().uid ?? userInfo().username ?? 'anon'); } catch { /* keep anon */ }
+  const dir = join(tmpdir(), `rsc-hooks-${uid}`);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  return dir;
+}
+
+// Keys are built from hook payload values, so they can contain anything. Flatten to a safe
+// filename — a key must never be able to point outside the marker directory.
+function safeName(key) {
+  return String(key).replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 200);
+}
+
+// Drop markers from previous days so the directory cannot grow without bound. Best-effort.
+function prune(dir, now) {
+  try {
+    for (const name of readdirSync(dir)) {
+      const p = join(dir, name);
+      try {
+        if (now - statSync(p).mtimeMs > PRUNE_AFTER_MS) unlinkSync(p);
+      } catch { /* raced with another hook — fine */ }
+    }
+  } catch { /* unreadable dir — fine */ }
+}
+
+/**
+ * Claim the right to emit `key` once.
+ *
+ * @returns true if this process should print, false if another scope already did.
+ *
+ * `windowMs` bounds how long a claim lasts. Two scopes fire within milliseconds of each other,
+ * while two genuine repeats of the same event (two compactions in one session, which reuse
+ * session_id AND source) are minutes apart — so an expired marker means "new event", not
+ * "duplicate". This window is the one heuristic in the design, and only SessionStart needs it:
+ * UserPromptSubmit keys on prompt_id, which is already unique per turn.
+ */
+export function claimOnce(key, { dir = markerDir(), windowMs = 30_000, now = Date.now() } = {}) {
+  try {
+    const file = join(dir, safeName(key));
+    try {
+      // Atomic create: whichever scope gets here first is the one that prints.
+      writeFileSync(file, String(now), { flag: 'wx' });
+      prune(dir, now);
+      return true;
+    } catch {
+      // Marker exists. Fresh → someone else already emitted this exact event.
+      const age = now - statSync(file).mtimeMs;
+      if (age <= windowMs) return false;
+      // Stale → this is a new occurrence of the same key. Re-arm and print.
+      const stamp = new Date(now);
+      utimesSync(file, stamp, stamp);
+      return true;
+    }
+  } catch {
+    return true; // fail-open
+  }
+}
+
+// The workflow gate text lives here, not inline in userprompt-gate.mjs, so it has exactly one
+// definition: the hook emits it and `rsc doctor` measures it from the same constant. Anything
+// that reports a byte count for text it does not own drifts the moment the text changes.
+export const WORKFLOW_GATE_TEXT = `===== workflow gate (highest precedence) =====
+Before acting on this turn: if the user wants to BUILD, ADD or CHANGE something — in ANY
+language, judged by intent, not by keywords — route it through the chain below FIRST. No
+feature code is written by ANY skill until the what is clear and the user has approved it.
+1. Not clear yet? -> \`grill-with-docs\` for a green idea or an open question; \`wayfinder\`
+   when the work is too large to hold in one session.
+2. Clear? -> \`to-spec\` writes the spec. Record every hard-to-reverse call with \`write-adr\`,
+   which leaves its trail under docs/adr/.
+3. Then build. Pick by size, and ask when unsure: ordinary work goes
+   \`superpowers:writing-plans\` -> \`superpowers:executing-plans\`; work that came out of
+   \`wayfinder\`, or too large for one plan, goes \`to-tickets\` -> \`implement\`, ticket by ticket.
+Always: \`superpowers:test-driven-development\`, and \`superpowers:verification-before-completion\`
+before calling anything done. Bugs enter through \`superpowers:systematic-debugging\`.
+One-line change, typo, or config bump? -> skip the chain, do it, say so.
+==============================================
+`;
+
+/**
+ * Parse the hook payload Claude Code writes to stdin.
+ * Pass `raw` explicitly in tests; in a hook, call with no argument to read fd 0.
+ * Any problem (no stdin, closed fd, malformed JSON) degrades to {} — callers then fail open.
+ */
+export function readHookInput(raw) {
+  try {
+    const text = raw === undefined ? readFileSync(0, 'utf8') : raw;
+    if (!text || !text.trim()) return {};
+    const parsed = JSON.parse(text);
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return {};
+  }
+}

package/targets/index.js

@@ -0,0 +1,184 @@
+import { existsSync, lstatSync, mkdirSync, rmSync, symlinkSync, cpSync, readFileSync } from 'node:fs';
+import { join, dirname, relative } from 'node:path';
+import { homedir } from 'node:os';
+import * as claudeAdapter from './claude.js';
+import * as cursorAdapter from './cursor.js';
+import * as mdAdapter from './_md-block.js';
+import { readManifest } from '../scripts/lib/manifest-file.js';
+
+// Project-local single source of truth. Real skill files live here exactly once;
+// every assistant gets a lightweight pointer (symlink) back to it — no duplication.
+export function baseDir(id, cwd = process.cwd()) {
+  return join(cwd, '.rsc', 'skills', id);
+}
+
+// Point an assistant's skill folder at the shared base. On macOS/Linux a relative
+// symlink avoids duplication. On Windows we copy real files: relative `dir`
+// symlinks require Developer Mode/admin and are not reliably followed by skill
+// discovery, so correctness wins over de-duplication. Idempotent: replaces any
+// existing link/dir at toPath.
+export function linkOrCopy(fromDir, toPath) {
+  mkdirSync(dirname(toPath), { recursive: true });
+  try { lstatSync(toPath); rmSync(toPath, { recursive: true, force: true }); } catch { /* nothing there */ }
+  if (process.platform === 'win32') {
+    cpSync(fromDir, toPath, { recursive: true });
+  } else {
+    try {
+      symlinkSync(relative(dirname(toPath), fromDir), toPath, 'dir');
+    } catch {
+      cpSync(fromDir, toPath, { recursive: true });
+    }
+  }
+  return [toPath];
+}
+
+// One row per assistant. `root` is where its skill folder lives (relative to the
+// project), `hook` is the file that gets the always-on suggest block, `adapter`
+// picks how skills + hook are written. `skillExt` (cursor only) means each skill
+// is a single converted file, not a linked directory.
+const SPEC = {
+  // JSON-hook + linked skill dirs
+  claude: { root: '.claude/skills', hook: '.claude/settings.json', adapter: 'claude' },
+  // Converted .mdc rules
+  cursor: { root: '.cursor/rules', hook: '.cursor/rules/rsc-suggest.mdc', adapter: 'cursor', skillExt: '.mdc' },
+  // AGENTS.md family — all read the same root AGENTS.md
+  codex: { root: '.codex/rsc', hook: 'AGENTS.md', adapter: 'md' },
+  opencode: { root: '.opencode/rsc', hook: 'AGENTS.md', adapter: 'md' },
+  amp: { root: '.amp/rsc', hook: 'AGENTS.md', adapter: 'md' },
+  jules: { root: '.jules/rsc', hook: 'AGENTS.md', adapter: 'md' },
+  zed: { root: '.zed/rsc', hook: 'AGENTS.md', adapter: 'md' },
+  // Own markdown instructions/rules file
+  gemini: { root: '.gemini/rsc', hook: 'GEMINI.md', adapter: 'md' },
+  antigravity: { root: '.antigravity/rsc', hook: '.antigravity/AGENTS.md', adapter: 'md' },
+  copilot: { root: '.github/rsc', hook: '.github/copilot-instructions.md', adapter: 'md' },
+  windsurf: { root: '.windsurf/rsc', hook: '.windsurf/rules/rsc-suggest.md', adapter: 'md' },
+  cline: { root: '.clinerules/rsc', hook: '.clinerules/rsc-suggest.md', adapter: 'md' },
+  roo: { root: '.roo/rsc', hook: '.roo/rules/rsc-suggest.md', adapter: 'md' },
+  continue: { root: '.continue/rsc', hook: '.continue/rules/rsc-suggest.md', adapter: 'md' },
+  junie: { root: '.junie/rsc', hook: '.junie/guidelines.md', adapter: 'md' },
+  kiro: { root: '.kiro/rsc', hook: '.kiro/steering/rsc-suggest.md', adapter: 'md' },
+  aider: { root: '.aider/rsc', hook: 'CONVENTIONS.md', adapter: 'md' },
+};
+
+const ADAPTER = { claude: claudeAdapter, cursor: cursorAdapter, md: mdAdapter };
+
+// Wizard multi-select list, in "most famous first" order. label/hint are display
+// only; detectTarget just pre-marks the one found in the folder.
+export const TARGETS = [
+  { id: 'claude', label: 'Claude Code', hint: '.claude/skills/' },
+  { id: 'codex', label: 'Codex CLI', hint: 'AGENTS.md' },
+  { id: 'copilot', label: 'GitHub Copilot', hint: '.github/copilot-instructions.md' },
+  { id: 'cursor', label: 'Cursor', hint: '.cursor/rules/' },
+  { id: 'gemini', label: 'Gemini CLI', hint: 'GEMINI.md' },
+  { id: 'windsurf', label: 'Windsurf', hint: '.windsurf/rules/' },
+  { id: 'cline', label: 'Cline', hint: '.clinerules/' },
+  { id: 'antigravity', label: 'Antigravity', hint: '.antigravity/' },
+  { id: 'zed', label: 'Zed', hint: 'AGENTS.md' },
+  { id: 'continue', label: 'Continue', hint: '.continue/rules/' },
+  { id: 'roo', label: 'Roo Code', hint: '.roo/rules/' },
+  { id: 'amp', label: 'Amp', hint: 'AGENTS.md' },
+  { id: 'opencode', label: 'opencode', hint: 'AGENTS.md' },
+  { id: 'jules', label: 'Jules', hint: 'AGENTS.md' },
+  { id: 'junie', label: 'JetBrains Junie', hint: '.junie/guidelines.md' },
+  { id: 'kiro', label: 'Kiro', hint: '.kiro/steering/' },
+  { id: 'aider', label: 'Aider', hint: 'CONVENTIONS.md' },
+];
+
+// Which assistants are actually installed here, read from the state file each one
+// writes. This is evidence: only an install of ours writes it. Everything below
+// (detectTarget) is inference from files a human — or our own `harness` skill —
+// may have written for unrelated reasons. Order follows SPEC so the ambiguity
+// message is deterministic. A missing, empty or unreadable state means "not
+// installed", never an error: a half-written file must not break resolution.
+export function installedTargets(cwd = process.cwd()) {
+  return TARGET_IDS.filter((id) => {
+    try {
+      const state = JSON.parse(readFileSync(targetPaths(id, undefined, cwd).stateFile, 'utf8'));
+      return Object.keys(state.skills || {}).length > 0;
+    } catch { return false; }
+  });
+}
+
+// Inference, used only when there is no evidence. Unique config dirs win.
+//
+// Two rules here are scar tissue from issue #249. Claude Code had NO signal at
+// all — it was merely the final fallthrough — so any repo with a root AGENTS.md
+// resolved to codex even with .claude/ full of skills. And AGENTS.md is the
+// weakest signal on purpose: our own `harness` skill writes one into every repo
+// it equips, so treating it as a strong hint made the harness poison its own
+// detection the moment it ran once.
+export function detectTarget(cwd = process.cwd()) {
+  const has = (p) => existsSync(join(cwd, p));
+  if (has('.cursor')) return 'cursor';
+  if (has('.windsurf')) return 'windsurf';
+  if (has('.clinerules')) return 'cline';
+  if (has('.roo')) return 'roo';
+  if (has('.continue')) return 'continue';
+  if (has('.junie')) return 'junie';
+  if (has('.kiro')) return 'kiro';
+  if (has('.zed')) return 'zed';
+  if (has('.opencode')) return 'opencode';
+  if (has('.amp')) return 'amp';
+  if (has('.jules')) return 'jules';
+  if (has('.antigravity')) return 'antigravity';
+  if (has(join('.github', 'copilot-instructions.md'))) return 'copilot';
+  if (has('.claude') || has('CLAUDE.md')) return 'claude';
+  if (has('.codex')) return 'codex';
+  if (has('.gemini') || has('GEMINI.md')) return 'gemini';
+  if (has('AGENTS.md')) return 'codex';       // weakest: our own harness writes this
+  return 'claude';
+}
+
+// The single point of truth for "which assistant are we acting on". Every command
+// goes through here — including doctor, which used to resolve on its own and so
+// could report a different target than the one just installed into.
+//
+// Ambiguity is a distinct outcome, not a value the caller might mistake for an id:
+// returning a sentinel string would let a forgetful caller pass it to targetPaths()
+// and die with `unknown target`. `ids` empty + `ambiguous` set cannot be used by
+// accident.
+export function resolveTargets({ cwd = process.cwd(), flagValue } = {}) {
+  if (typeof flagValue === 'string' && flagValue.trim()) {
+    const ids = flagValue.split(',').map((s) => s.trim()).filter(Boolean);
+    return { ids, ambiguous: null, source: 'flag' };
+  }
+  // The committed manifest is what the team decided, so it outranks what happens to be
+  // on this machine. Two targets here is not ambiguity — it is the team saying "both".
+  const declared = readManifest(cwd)?.targets || [];
+  if (declared.length) return { ids: declared, ambiguous: null, source: 'manifest' };
+  const found = installedTargets(cwd);
+  if (found.length === 1) return { ids: found, ambiguous: null, source: 'evidence' };
+  if (found.length > 1) return { ids: [], ambiguous: found, source: 'evidence' };
+  return { ids: [detectTarget(cwd)], ambiguous: null, source: 'heuristic' };
+}
+
+export function targetPaths(target, home = homedir(), cwd = process.cwd()) {
+  const s = SPEC[target];
+  if (!s) throw new Error(`unknown target ${target}`);
+  const rootAbs = join(cwd, ...s.root.split('/'));
+  return {
+    root: rootAbs,
+    projectRoot: cwd,
+    skillDir: (id) => (s.skillExt ? join(rootAbs, `${id}${s.skillExt}`) : join(rootAbs, id)),
+    stateFile: join(rootAbs, '.rsc-state.json'),
+    hookTarget: join(cwd, ...s.hook.split('/')),
+  };
+}
+
+export function writeSkill(target, id, fromDir, toPath) {
+  return ADAPTER[SPEC[target].adapter].writeSkill(id, fromDir, toPath);
+}
+
+export function wireHook(target, paths, sourceMd, policy) {
+  return ADAPTER[SPEC[target].adapter].wireHook(paths, sourceMd, policy);
+}
+
+// Inverse of wireHook — remove rsc's always-on surface for a target (settings.json
+// hook entries / AGENTS-block / cursor rule file). Returns the paths it touched.
+export function unwireHook(target, paths) {
+  const adapter = ADAPTER[SPEC[target].adapter];
+  return adapter.unwireHook ? adapter.unwireHook(paths) : [];
+}
+
+// Every known target id — used by `purge` to sweep all assistants, installed or not.
+export const TARGET_IDS = Object.keys(SPEC);

package/targets/memory.js

@@ -0,0 +1,276 @@
+import {
+  appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync,
+} from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+export { handleLifecycle, contextFromNativeOutput } from './session-memory-adapter.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const NEEDLE = '.rsc/session-memory-adapter.mjs';
+const PLUGIN_MARKER = 'rsc-memory:managed';
+
+export const MEMORY_TARGETS = Object.freeze({
+  claude: 'full',
+  codex: 'full',
+  // Cursor documents sessionStart as fire-and-forget. Its best-effort hook is useful,
+  // but only the always-on rule can make the read-before-action obligation explicit.
+  cursor: 'assisted',
+  gemini: 'full',
+  opencode: 'full',
+});
+
+const CONFIG = Object.freeze({
+  claude: '.claude/settings.local.json',
+  codex: '.codex/hooks.json',
+  cursor: '.cursor/hooks.json',
+  gemini: '.gemini/settings.json',
+  opencode: '.opencode/plugins/rsc-memory.js',
+});
+
+export const memoryModeFor = (target) => MEMORY_TARGETS[target] || 'unsupported';
+
+export function memoryEnabledForProject(cwd = process.cwd()) {
+  try { return JSON.parse(readFileSync(join(cwd, '.rsc.json'), 'utf8')).memory !== false; } catch { return true; }
+}
+
+function git(cwd, args) {
+  try { return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { return null; }
+}
+
+function rel(cwd, path) {
+  return relative(cwd, path).split(sep).join('/');
+}
+
+function tracked(cwd, path) {
+  const output = git(cwd, ['ls-files', '--', rel(cwd, path)]);
+  return Boolean(output);
+}
+
+function exclude(cwd, path) {
+  if (git(cwd, ['rev-parse', '--is-inside-work-tree']) !== 'true') return;
+  const value = git(cwd, ['rev-parse', '--git-path', 'info/exclude']);
+  if (!value) return;
+  const file = isAbsolute(value) ? value : resolve(cwd, value);
+  const pattern = `/${rel(cwd, path)}`;
+  mkdirSync(dirname(file), { recursive: true });
+  const body = existsSync(file) ? readFileSync(file, 'utf8') : '';
+  if (!body.split('\n').includes(pattern)) appendFileSync(file, `${body && !body.endsWith('\n') ? '\n' : ''}${pattern}\n`);
+}
+
+function readConfig(path) {
+  if (!existsSync(path)) return {};
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return null; }
+}
+
+function validHookConfig(config) {
+  if (!config || typeof config !== 'object' || Array.isArray(config)) return false;
+  if (!Object.hasOwn(config, 'hooks')) return true;
+  if (!config.hooks || typeof config.hooks !== 'object' || Array.isArray(config.hooks)) return false;
+  return Object.values(config.hooks).every(Array.isArray);
+}
+
+function handler(target, event) {
+  const unixScript = target === 'claude'
+    ? '"${CLAUDE_PROJECT_DIR}/.rsc/session-memory-adapter.mjs"'
+    : target === 'codex'
+      ? '"$(git rev-parse --show-toplevel)/.rsc/session-memory-adapter.mjs"'
+      : '".rsc/session-memory-adapter.mjs"';
+  const value = {
+    type: 'command',
+    command: `node ${unixScript} ${target} ${event}`,
+    timeout: target === 'gemini' ? 5000 : event === 'end' && target === 'codex' ? 3 : 5,
+  };
+  if (target === 'codex') {
+    value.commandWindows = `node \"$((git rev-parse --show-toplevel).Trim())/.rsc/session-memory-adapter.mjs\" ${target} ${event}`;
+    value.additionalContextLimit = 1400;
+  }
+  if (target === 'gemini') value.name = `rsc-memory-${event}`;
+  return value;
+}
+
+const nestedEvents = {
+  claude: [
+    ['SessionStart', 'start'], ['UserPromptSubmit', 'request'], ['PostToolUse', 'edit', 'Edit|Write|NotebookEdit'],
+    ['PostToolUse', 'boundary', 'Bash'], ['Stop', 'turn'], ['PreCompact', 'compact'], ['SessionEnd', 'end'],
+  ],
+  codex: [
+    ['SessionStart', 'start', 'startup|resume|clear|compact'], ['UserPromptSubmit', 'request'],
+    ['PostToolUse', 'edit', 'apply_patch|Edit|Write'], ['PostToolUse', 'boundary', 'Bash'],
+    ['Stop', 'turn'], ['PreCompact', 'compact'], ['SessionEnd', 'end'],
+  ],
+  gemini: [
+    ['SessionStart', 'start'], ['BeforeAgent', 'request'], ['AfterTool', 'edit', 'write_file|replace'],
+    ['AfterTool', 'boundary', 'run_shell_command'], ['AfterAgent', 'turn'], ['PreCompress', 'compact'], ['SessionEnd', 'end'],
+  ],
+};
+
+const cursorEvents = [
+  ['sessionStart', 'start'], ['beforeSubmitPrompt', 'request'], ['afterFileEdit', 'edit'],
+  ['afterShellExecution', 'boundary'], ['afterAgentResponse', 'turn'], ['preCompact', 'compact'], ['sessionEnd', 'end'],
+];
+
+function stripManaged(config) {
+  if (!validHookConfig(config) || !config.hooks) return config;
+  for (const event of Object.keys(config.hooks)) {
+    config.hooks[event] = (config.hooks[event] || []).filter((entry) => !JSON.stringify(entry).replaceAll('\\\\', '/').includes(NEEDLE));
+    if (!config.hooks[event].length) delete config.hooks[event];
+  }
+  if (!Object.keys(config.hooks).length) delete config.hooks;
+  return config;
+}
+
+function writeJsonWiring(target, path, config) {
+  stripManaged(config);
+  config.hooks ||= {};
+  if (target === 'cursor') {
+    config.version ||= 1;
+    for (const [event, operation] of cursorEvents) {
+      config.hooks[event] ||= [];
+      const entry = handler(target, operation);
+      delete entry.type;
+      delete entry.timeout;
+      config.hooks[event].push(entry);
+    }
+  } else {
+    for (const [event, operation, matcher] of nestedEvents[target]) {
+      config.hooks[event] ||= [];
+      config.hooks[event].push({ ...(matcher ? { matcher } : {}), hooks: [handler(target, operation)] });
+    }
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`);
+}
+
+function commonPaths(cwd) {
+  return [
+    join(cwd, '.rsc', 'session-memory-core.mjs'),
+    join(cwd, '.rsc', 'session-memory-adapter.mjs'),
+    join(cwd, '.rsc', 'session-memory.mjs'),
+  ];
+}
+
+export function memoryManagedPaths(target, cwd = process.cwd()) {
+  if (!MEMORY_TARGETS[target]) return [];
+  const paths = [...commonPaths(cwd), join(cwd, ...CONFIG[target].split('/'))];
+  if (target === 'cursor') paths.push(join(cwd, '.cursor', 'rules', 'rsc-memory.mdc'));
+  return paths;
+}
+
+export function wireMemory(target, cwd = process.cwd()) {
+  const mode = memoryModeFor(target);
+  if (mode === 'unsupported') return { mode, reason: 'no-local-lifecycle', paths: [] };
+  if (!memoryEnabledForProject(cwd)) {
+    unwireMemory(target, cwd);
+    return { mode: 'disabled', reason: 'project-disabled', paths: [] };
+  }
+  const configPath = join(cwd, ...CONFIG[target].split('/'));
+  if (tracked(cwd, configPath)) return { mode: 'degraded', reason: 'config-tracked', paths: [] };
+  const config = target === 'opencode' ? null : readConfig(configPath);
+  if (target !== 'opencode' && !validHookConfig(config)) return { mode: 'degraded', reason: 'config-invalid', paths: [] };
+  if (target === 'opencode' && existsSync(configPath) && !readFileSync(configPath, 'utf8').includes(PLUGIN_MARKER)) {
+    return { mode: 'degraded', reason: 'plugin-collision', paths: [] };
+  }
+  const assistedRule = join(cwd, '.cursor', 'rules', 'rsc-memory.mdc');
+  if (target === 'cursor' && tracked(cwd, assistedRule)) return { mode: 'degraded', reason: 'rule-tracked', paths: [] };
+  if (target === 'cursor' && existsSync(assistedRule) && !readFileSync(assistedRule, 'utf8').includes('rsc-memory:managed')) {
+    return { mode: 'degraded', reason: 'rule-collision', paths: [] };
+  }
+
+  const [core, adapter, cli] = commonPaths(cwd);
+  mkdirSync(dirname(core), { recursive: true });
+  copyFileSync(join(HERE, 'session-memory-core.mjs'), core);
+  copyFileSync(join(HERE, 'session-memory-adapter.mjs'), adapter);
+  copyFileSync(join(HERE, 'session-memory.mjs'), cli);
+  if (target === 'opencode') {
+    mkdirSync(dirname(configPath), { recursive: true });
+    copyFileSync(join(HERE, 'opencode-memory-plugin.js'), configPath);
+  } else {
+    writeJsonWiring(target, configPath, config);
+  }
+  if (target === 'cursor') {
+    mkdirSync(dirname(assistedRule), { recursive: true });
+    writeFileSync(assistedRule, `---\ndescription: Read rsc local continuation before the first action in a new desktop session.\nalwaysApply: true\n---\n<!-- rsc-memory:managed -->\nOn the first turn of a local desktop session, run \`node .rsc/session-memory.mjs resume\` and read its \`context\` field before acting. Skip this rule for background or cloud agents.\n`);
+  }
+  const paths = memoryManagedPaths(target, cwd);
+  for (const path of paths) exclude(cwd, path);
+  return {
+    mode,
+    reason: target === 'codex' ? 'hook-trust-required' : target === 'cursor' ? 'start-hook-fire-and-forget' : 'wired',
+    paths,
+  };
+}
+
+export function inspectMemoryWiring(target, cwd = process.cwd(), recorded = null, installed = false) {
+  const supportedMode = memoryModeFor(target);
+  if (supportedMode === 'unsupported') return { supportedMode, mode: 'unsupported', status: 'unsupported', reason: 'no-local-lifecycle', missing: [], tracked: [] };
+  const mode = recorded?.mode || 'not-installed';
+  if (mode === 'disabled' || !memoryEnabledForProject(cwd)) {
+    return { supportedMode, mode: 'disabled', status: 'disabled', reason: 'project-disabled', missing: [], tracked: [] };
+  }
+  // A capability that has never been installed is absent, not broken. Keep the
+  // degraded state for pre-memory installs so `sync` can repair those projects.
+  if (!recorded && !installed) {
+    return { supportedMode, mode, status: 'not-installed', reason: 'not-wired', missing: [], tracked: [] };
+  }
+  const paths = recorded?.paths?.length ? recorded.paths : memoryManagedPaths(target, cwd);
+  const configPath = join(cwd, ...CONFIG[target].split('/'));
+  const cursorRule = join(cwd, '.cursor', 'rules', 'rsc-memory.mdc');
+  const missing = paths.filter((path) => {
+    if (!existsSync(path)) return true;
+    if (path === configPath) {
+      const body = readFileSync(path, 'utf8').replaceAll('\\', '/');
+      return target === 'opencode' ? !body.includes(PLUGIN_MARKER) : !body.includes(NEEDLE);
+    }
+    if (target === 'cursor' && path === cursorRule) return !readFileSync(path, 'utf8').includes(PLUGIN_MARKER);
+    return false;
+  });
+  const trackedPaths = paths.filter((path) => tracked(cwd, path));
+  const status = mode === 'degraded' || mode === 'not-installed' || missing.length || trackedPaths.length ? 'degraded' : 'ready';
+  return {
+    supportedMode,
+    mode,
+    status,
+    reason: mode === 'degraded' ? (recorded?.reason || 'adapter-degraded')
+      : trackedPaths.length ? 'memory-path-tracked'
+        : missing.length ? 'memory-path-missing'
+          : recorded?.reason || 'wired',
+    missing,
+    tracked: trackedPaths,
+    action: status === 'degraded' ? 'Run `npx @damiangilgonzalez/harness sync`; if a config is tracked, move memory hooks to an untracked local config first.' : null,
+    trustRequired: target === 'codex' && status === 'ready',
+  };
+}
+
+export function unwireMemory(target, cwd = process.cwd()) {
+  if (!MEMORY_TARGETS[target]) return [];
+  const path = join(cwd, ...CONFIG[target].split('/'));
+  const touched = [];
+  if (target === 'opencode') {
+    if (existsSync(path) && readFileSync(path, 'utf8').includes(PLUGIN_MARKER)) { rmSync(path, { force: true }); touched.push(path); }
+  } else {
+    const raw = existsSync(path) ? readFileSync(path, 'utf8') : '';
+    const config = raw.replaceAll('\\\\', '/').includes(NEEDLE) ? readConfig(path) : null;
+    if (config) { stripManaged(config); writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`); touched.push(path); }
+  }
+  if (target === 'cursor') {
+    const rule = join(cwd, '.cursor', 'rules', 'rsc-memory.mdc');
+    if (existsSync(rule) && readFileSync(rule, 'utf8').includes('rsc-memory:managed')) { rmSync(rule, { force: true }); touched.push(rule); }
+  }
+  return touched;
+}
+
+export function memoryArtifactsPresent(target, cwd = process.cwd()) {
+  if (!MEMORY_TARGETS[target]) return [];
+  const out = commonPaths(cwd).filter(existsSync);
+  const config = join(cwd, ...CONFIG[target].split('/'));
+  if (existsSync(config)) {
+    const body = readFileSync(config, 'utf8').replaceAll('\\\\', '/');
+    if (body.includes(NEEDLE) || body.includes(PLUGIN_MARKER)) out.push(config);
+  }
+  if (target === 'cursor') {
+    const rule = join(cwd, '.cursor', 'rules', 'rsc-memory.mdc');
+    if (existsSync(rule) && readFileSync(rule, 'utf8').includes('rsc-memory:managed')) out.push(rule);
+  }
+  return out;
+}

package/targets/opencode-memory-plugin.js

@@ -0,0 +1,65 @@
+// rsc-memory:managed
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { capture, resume } from '../../.rsc/session-memory-core.mjs';
+
+function memorySettings(cwd) {
+  try {
+    const value = JSON.parse(readFileSync(join(cwd, '.rsc.json'), 'utf8')).memory;
+    if (value === false) return { enabled: false };
+    return value && typeof value === 'object' ? value : {};
+  } catch {
+    return {};
+  }
+}
+
+function sessionId(input) {
+  return input?.sessionID || input?.session_id || input?.event?.properties?.info?.id
+    || input?.event?.properties?.sessionID || null;
+}
+
+export const RscMemoryPlugin = async ({ directory, worktree }) => {
+  const cwd = worktree || directory;
+  const injected = new Set();
+  const local = () => process.env.RSC_REMOTE_AGENT !== '1' && process.env.OPENCODE_REMOTE !== '1';
+  const save = (id, event, editDelta = 0) => {
+    if (!id || !local()) return;
+    try { capture({ cwd, sessionId: id, target: 'opencode', event, editDelta, settings: memorySettings(cwd) }); } catch { /* fail open */ }
+  };
+
+  return {
+    'experimental.chat.system.transform': async (input, output) => {
+      const id = sessionId(input);
+      if (!id || injected.has(id) || !local()) return;
+      injected.add(id);
+      try {
+        const config = memorySettings(cwd);
+        save(id, 'start');
+        const result = resume({ cwd, target: 'opencode', settings: config });
+        if (!result.context || !Array.isArray(output?.system)) return;
+        if (output.system.length === 0) output.system.push(result.context);
+        else output.system[0] = `${output.system[0]}\n\n${result.context}`;
+      } catch { /* fail open */ }
+    },
+    'tool.execute.after': async (input) => {
+      const tool = String(input?.tool || '').toLowerCase();
+      save(sessionId(input), 'boundary', /write|edit|patch/u.test(tool) ? 1 : 0);
+    },
+    'experimental.session.compacting': async (input, output) => {
+      const id = sessionId(input);
+      save(id, 'compact');
+      try {
+        const result = resume({ cwd, target: 'opencode', settings: memorySettings(cwd) });
+        if (result.context && Array.isArray(output?.context)) output.context.push(result.context);
+      } catch { /* fail open */ }
+    },
+    event: async ({ event }) => {
+      const id = sessionId({ event });
+      if (event?.type === 'session.created') save(id, 'start');
+      else if (event?.type === 'file.edited') save(id, 'edit', 1);
+      else if (event?.type === 'session.compacted') save(id, 'compact');
+      else if (event?.type === 'session.idle') save(id, 'turn');
+      else if (event?.type === 'session.deleted') save(id, 'sessionEnd');
+    },
+  };
+};