supipowers 2.0.2 → 2.1.0

package/src/harness/storage.ts

@@ -29,15 +29,22 @@ import {
   getHarnessDecisionsPath,
   getHarnessDesignSpecJsonPath,
   getHarnessDiscoverPath,
+  getHarnessDocsStagingDir,
+  getHarnessDocsStagingLayerPath,
+  getHarnessDocsStagingReadmePath,
   getHarnessImplementLogPath,
   getHarnessManifestPath,
   getHarnessPipelineLogPath,
   getHarnessQueuePath,
+  getHarnessRepoDocsLayerPath,
+  getHarnessRepoDocsLayersDir,
+  getHarnessRepoDocsReadmePath,
   getHarnessRepoScorePath,
   getHarnessResearchTopicPath,
   getHarnessScoreHistoryPath,
   getHarnessSessionDir,
   getHarnessValidateReportPath,
+  HARNESS_DOCS_LAYERS_DIRNAME,
 } from "./project-paths.js";
 
 // ---------------------------------------------------------------------------
@@ -418,6 +425,44 @@ export function appendImplementLog(
   return appendJsonl(getHarnessImplementLogPath(paths, cwd, sessionId), record);
 }
 
+/**
+ * Return true if the implement log records a successful programmatic apply for this
+ * session: the most recent record has `kind: "applied"` and an empty `errors` array.
+ * Used by `HarnessImplementStage.isComplete` to fast-skip reruns.
+ */
+export function hasSuccessfulImplementApply(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+): boolean {
+  const logPath = getHarnessImplementLogPath(paths, cwd, sessionId);
+  if (!fs.existsSync(logPath)) return false;
+  let raw: string;
+  try {
+    raw = fs.readFileSync(logPath, "utf8");
+  } catch {
+    return false;
+  }
+  // Scan from the end so a later failed re-apply correctly overrides an earlier success.
+  const lines = raw.split("\n");
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i].trim();
+    if (line.length === 0) continue;
+    let record: unknown;
+    try {
+      record = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (!record || typeof record !== "object" || Array.isArray(record)) continue;
+    const r = record as { kind?: unknown; errors?: unknown };
+    if (r.kind !== "applied") continue;
+    const errCount = Array.isArray(r.errors) ? r.errors.length : 0;
+    return errCount === 0;
+  }
+  return false;
+}
+
 // ---------------------------------------------------------------------------
 // Project-scoped queue + score (shared across worktrees)
 // ---------------------------------------------------------------------------
@@ -465,3 +510,100 @@ export function appendScoreHistory(
 ): UltraPlanStorageResult<string> {
   return appendJsonl(getHarnessScoreHistoryPath(paths, cwd), record);
 }
+
+// ---------------------------------------------------------------------------
+// Docs stage — staging + repo promotion.
+// ---------------------------------------------------------------------------
+
+/** Save a single layer doc into the session's staging area. Atomic write. */
+export function saveHarnessDocsLayerStaging(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  layerId: string,
+  markdown: string,
+): UltraPlanStorageResult<string> {
+  return writeTextAtomic(
+    getHarnessDocsStagingLayerPath(paths, cwd, sessionId, layerId),
+    markdown,
+  );
+}
+
+/** Read a single staged layer doc. */
+export function loadHarnessDocsLayerStaging(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  layerId: string,
+): UltraPlanStorageResult<string> {
+  return readTextFile(getHarnessDocsStagingLayerPath(paths, cwd, sessionId, layerId));
+}
+
+/** List staged layer ids (file basenames without `.md`). Returns [] when dir is absent. */
+export function listHarnessDocsLayerStaging(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+): string[] {
+  const dir = path.join(
+    getHarnessDocsStagingDir(paths, cwd, sessionId),
+    HARNESS_DOCS_LAYERS_DIRNAME,
+  );
+  if (!fs.existsSync(dir)) return [];
+  try {
+    return fs
+      .readdirSync(dir)
+      .filter((name) => name.endsWith(".md"))
+      .map((name) => name.slice(0, -3))
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+/** Save the staged docs index. Atomic write. */
+export function saveHarnessDocsIndexStaging(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  markdown: string,
+): UltraPlanStorageResult<string> {
+  return writeTextAtomic(getHarnessDocsStagingReadmePath(paths, cwd, sessionId), markdown);
+}
+
+/**
+ * Promote staged docs to the repo-local docs/ tree.
+ *
+ * Atomicity contract: layer docs are written first (each via temp → rename); the index
+ * is written last so an observer reading mid-promotion never sees an index pointing at
+ * a yet-to-land layer doc. A failure midway leaves the previous repo state in place for
+ * already-rewritten files only when their layer was earlier in the list — callers must
+ * therefore treat partial failures as a "blocked" outcome and rely on the next run to
+ * re-promote from staging.
+ */
+export function promoteHarnessDocsToRepo(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  layerIds: readonly string[],
+): UltraPlanStorageResult<{ layerPaths: string[]; indexPath: string }> {
+  fs.mkdirSync(getHarnessRepoDocsLayersDir(paths, cwd), { recursive: true });
+
+  const layerPaths: string[] = [];
+  for (const layerId of layerIds) {
+    const staged = loadHarnessDocsLayerStaging(paths, cwd, sessionId, layerId);
+    if (!staged.ok) return staged;
+    const repoPath = getHarnessRepoDocsLayerPath(paths, cwd, layerId);
+    const wrote = writeTextAtomic(repoPath, staged.value);
+    if (!wrote.ok) return wrote;
+    layerPaths.push(wrote.value);
+  }
+
+  const indexStaged = readTextFile(getHarnessDocsStagingReadmePath(paths, cwd, sessionId));
+  if (!indexStaged.ok) return indexStaged;
+  const indexRepo = getHarnessRepoDocsReadmePath(paths, cwd);
+  const wroteIndex = writeTextAtomic(indexRepo, indexStaged.value);
+  if (!wroteIndex.ok) return wroteIndex;
+
+  return success({ layerPaths, indexPath: wroteIndex.value });
+}

package/src/harness/tools.ts

@@ -28,6 +28,7 @@ import {
   appendImplementLog,
   saveHarnessDesignSpec,
   saveHarnessDiscover,
+  saveHarnessDocsLayerStaging,
   saveHarnessResearchTopic,
 } from "./storage.js";
 import {
@@ -36,6 +37,8 @@ import {
   resolve as resolveQueueEntry,
   markWontfix as markQueueWontfix,
 } from "./anti_slop/queue.js";
+import { validateLayerDocMarkdown } from "./docs/validator.js";
+import { isSafeLayerId } from "./project-paths.js";
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -410,6 +413,79 @@ export function registerHarnessPipelineTools(platform: Platform): void {
       return toolResult({ ok: true, id, details: { state } });
     },
   });
+
+  // -------- harness_docs_record ----------
+  platform.registerTool({
+    name: "harness_docs_record",
+    label: "Harness Docs Record",
+    description: "Record one per-layer agent knowledge document for the docs stage.",
+    parameters: {
+      type: "object",
+      properties: {
+        sessionId: SESSION_ID_PROP,
+        layerId: {
+          type: "string",
+          description: "Layer id this doc covers (matches the assigned layer rule).",
+        },
+        markdown: {
+          type: "string",
+          description: "Full markdown body, including the provenance marker, frontmatter, and required headings.",
+        },
+      },
+      required: ["sessionId", "layerId", "markdown"],
+    },
+    async execute(_id: string, params: unknown, _signal: AbortSignal, _onUpdate: unknown, toolCtx: unknown) {
+      const cwdR = readCwd(toolCtx, "harness_docs_record");
+      if (!cwdR.ok) return toolResult(cwdR);
+      const sidR = readSessionId(params, "harness_docs_record");
+      if (!sidR.ok) return toolResult(sidR);
+      if (!isRecord(params)) {
+        return toolResult({ ok: false, message: "harness_docs_record requires an object payload" });
+      }
+      const p = params as Record<string, unknown>;
+      const layerId = typeof p.layerId === "string" ? p.layerId : "";
+      if (!layerId) {
+        return toolResult({ ok: false, message: "harness_docs_record requires a non-empty layerId" });
+      }
+      if (!isSafeLayerId(layerId)) {
+        return toolResult({
+          ok: false,
+          message: `harness_docs_record: layerId ${JSON.stringify(layerId)} is not a safe filename stem (alnum/_/-/non-leading dots, ≤64 chars, no '..' or path separators)`,
+        });
+      }
+      const markdown = typeof p.markdown === "string" ? p.markdown : "";
+      if (markdown.length === 0) {
+        return toolResult({ ok: false, message: "harness_docs_record requires a non-empty markdown body" });
+      }
+
+      const expectation = lookupDocsLayerExpectation(sidR.sessionId, layerId);
+      if (!expectation) {
+        return toolResult({
+          ok: false,
+          message: `harness_docs_record: no expectation registered for session ${sidR.sessionId} layer ${layerId}. The docs stage is the only valid invocation context.`,
+        });
+      }
+
+      const validation = validateLayerDocMarkdown(markdown, {
+        expectedLayerId: layerId,
+        expectedSourceHash: expectation.expectedSourceHash,
+        maxDocLoc: expectation.maxDocLoc,
+        maxAgentContextLoc: expectation.maxAgentContextLoc,
+      });
+      if (!validation.ok) {
+        return toolResult({
+          ok: false,
+          message: `harness_docs_record rejected: ${validation.errors.join("; ")}`,
+          details: { errors: validation.errors },
+        });
+      }
+
+      const persisted = saveHarnessDocsLayerStaging(platform.paths, cwdR.cwd, sidR.sessionId, layerId, markdown);
+      const r = unwrap(persisted, "harness_docs_record");
+      if (!r.ok) return toolResult(r);
+      return toolResult({ ok: true, path: r.value });
+    },
+  });
 }
 
 /** Names exposed for hook-bridge correlation. */
@@ -421,6 +497,60 @@ export const HARNESS_PIPELINE_TOOL_NAMES = [
   "harness_validate_finding",
   "harness_slop_queue_append",
   "harness_slop_queue_resolve",
+  "harness_docs_record",
 ] as const;
 
 export type HarnessPipelineToolName = (typeof HARNESS_PIPELINE_TOOL_NAMES)[number];
+
+// ---------------------------------------------------------------------------
+// Docs stage expectations registry.
+//
+// The docs stage registers per-(session, layer) expectations before dispatching each
+// subagent so the `harness_docs_record` handler can validate `layerId`, `sourceHash`,
+// and LOC caps synchronously. Module-scoped Map is intentional: registration and
+// consumption both run in the same process within a single pipeline driver invocation.
+// ---------------------------------------------------------------------------
+
+export interface HarnessDocsLayerExpectation {
+  expectedSourceHash: string;
+  maxDocLoc: number;
+  maxAgentContextLoc: number;
+}
+
+const docsLayerExpectations = new Map<string, HarnessDocsLayerExpectation>();
+
+function docsKey(sessionId: string, layerId: string): string {
+  return `${sessionId}::${layerId}`;
+}
+
+/** Register the expectations the docs tool will validate on the next record call. */
+export function registerDocsLayerExpectation(
+  sessionId: string,
+  layerId: string,
+  expectation: HarnessDocsLayerExpectation,
+): void {
+  if (!isSafeLayerId(layerId)) {
+    throw new Error(
+      `registerDocsLayerExpectation: refusing to register unsafe layerId ${JSON.stringify(layerId)}`,
+    );
+  }
+  docsLayerExpectations.set(docsKey(sessionId, layerId), expectation);
+}
+
+/** Remove a registered expectation. Idempotent. */
+export function clearDocsLayerExpectation(sessionId: string, layerId: string): void {
+  docsLayerExpectations.delete(docsKey(sessionId, layerId));
+}
+
+/** Lookup the registered expectation (returns null when none is registered). */
+export function lookupDocsLayerExpectation(
+  sessionId: string,
+  layerId: string,
+): HarnessDocsLayerExpectation | null {
+  return docsLayerExpectations.get(docsKey(sessionId, layerId)) ?? null;
+}
+
+/** Clear every registration (test helper). */
+export function _clearAllDocsLayerExpectationsForTests(): void {
+  docsLayerExpectations.clear();
+}

package/src/mempalace/bridge.ts

@@ -1,5 +1,8 @@
+import { homedir } from "node:os";
+import * as path from "node:path";
+
 import type { ResolvedMempalaceConfig } from "./config.js";
-import type { MempalaceParams } from "./schema.js";
+import { MEMPALACE_ACTIONS, type MempalaceAction, type MempalaceParams } from "./schema.js";
 import {
   resolveBridgeScriptPath,
   resolveManagedVenvPaths,
@@ -24,6 +27,11 @@ export type MempalaceBridgeCallResult =
       diagnostics: Record<string, unknown>;
     };
 
+interface BridgeDispatchResult {
+  result: MempalaceBridgeCallResult;
+  release: Promise<void>;
+}
+
 export interface MempalaceBridgeRuntimeDeps {
   resolveBridgeScriptPath?: () => BridgePathResult;
   runBridgeRequest?: (options: RunBridgeRequestOptions) => Promise<RunBridgeRequestResult>;
@@ -54,6 +62,102 @@ function mergeDiagnostics(...parts: Array<Record<string, unknown> | undefined>):
   return Object.assign({}, ...parts.filter(Boolean));
 }
 
+// Per-action mutation classification. `write` actions are serialized per palace
+// to avoid ChromaDB's sqlite "database is locked" errors; `read` actions run in
+// parallel. The classification is exhaustive (enforced by `satisfies`) so any
+// new action added to MEMPALACE_ACTIONS must be assigned a kind here — no
+// silent default to the read path. `setup` is intercepted before the bridge and
+// never reaches this map; it is still listed for exhaustiveness.
+const ACTION_KIND = {
+  // ── reads / queries / listings ──────────────────────────────────────────
+  status: "read",
+  list_wings: "read",
+  list_rooms: "read",
+  get_taxonomy: "read",
+  search: "read",
+  check_duplicate: "read",
+  get_aaak_spec: "read",
+  get_drawer: "read",
+  list_drawers: "read",
+  kg_query: "read",
+  kg_timeline: "read",
+  kg_stats: "read",
+  traverse: "read",
+  find_tunnels: "read",
+  graph_stats: "read",
+  list_tunnels: "read",
+  follow_tunnels: "read",
+  diary_read: "read",
+  hook_settings: "read",
+  memories_filed_away: "read",
+  reconnect: "read",
+  version: "read",
+  wake_up: "read",
+  wake_up_and_search: "read",
+  setup: "read", // intercepted upstream; never reaches the bridge mutex
+
+  // ── writes / mutations ──────────────────────────────────────────────────
+  add_drawer: "write",
+  update_drawer: "write",
+  delete_drawer: "write",
+  diary_write: "write",
+  kg_add: "write",
+  kg_invalidate: "write",
+  create_tunnel: "write",
+  delete_tunnel: "write",
+  // CLI actions that touch the palace on disk: init creates structure,
+  // mine writes drawers via the indexer, split rewrites mega-file sources
+  // under the palace tree, repair rebuilds the chroma index. All four must
+  // serialize against concurrent add_drawer/diary_write writers on the
+  // same palace.
+  init: "write",
+  mine: "write",
+  split: "write",
+  repair: "write",
+} as const satisfies Record<MempalaceAction, "read" | "write">;
+
+// Compile-time check: every MEMPALACE_ACTIONS entry must have a kind.
+// If a new action is added without an ACTION_KIND entry, this errors.
+type _ExhaustiveActionKind = MempalaceAction extends keyof typeof ACTION_KIND ? true : never;
+const _exhaustiveActionKind: _ExhaustiveActionKind = true;
+void _exhaustiveActionKind;
+void MEMPALACE_ACTIONS;
+
+function isWriteAction(action: MempalaceAction): boolean {
+  return ACTION_KIND[action] === "write";
+}
+
+// Subset of write actions where a single retry on transient bridge failures
+// meaningfully improves durability (write-once payloads, low retry cost).
+const RETRY_ON_TRANSIENT = new Set<MempalaceAction>([
+  "add_drawer", "diary_write", "kg_add", "kg_invalidate",
+]);
+
+// Error codes that are transient and safe to retry. `bridge_timeout` is
+// deliberately excluded: when the TS-side timeout fires we SIGKILL the python
+// child, but the OS may not have reaped the writer yet — retrying could race a
+// still-live writer on the same sqlite file. `bridge_process_failed` only
+// fires after `child.on('close')`, so the child is definitely gone by then.
+const TRANSIENT_ERROR_CODES = new Set(["bridge_process_failed"]);
+
+// Per-palace write serialization queue. Keyed by the canonicalized palace
+// path so that concurrent OMP workspaces (different palaces) do not block each
+// other, and so callers passing `~/x` vs `/Users/me/x` collide on the same
+// lock (they hit the same sqlite file). Entries are deleted in a settlement
+// handler when they still point at the current tail, keeping the map bounded
+// in long-lived OMP processes.
+const palaceMutex = new Map<string, Promise<void>>();
+const RELEASED = Promise.resolve<void>(undefined);
+
+function canonicalPalaceKey(palacePath: string): string {
+  const trimmed = palacePath.trim();
+  if (trimmed === "~") return homedir();
+  const expanded = (trimmed.startsWith("~/") || trimmed.startsWith("~\\"))
+    ? path.join(homedir(), trimmed.slice(2))
+    : trimmed;
+  return path.isAbsolute(expanded) ? path.normalize(expanded) : path.resolve(expanded);
+}
+
 function resolveToolTimeoutMs(params: MempalaceParams, bridgeTimeoutMs: number): number {
   if (typeof params.timeout !== "number") return bridgeTimeoutMs;
 
@@ -81,55 +185,117 @@ export function createMempalaceBridge(options: CreateMempalaceBridgeOptions): Me
       const venv = resolveManagedVenvPaths(options.config.managedVenvPath);
       const timeoutMs = resolveToolTimeoutMs(params, options.config.timeouts.bridgeMs);
       const palacePath = params.palace ?? options.config.palacePath;
-      const runResult = await runBridge({
-        pythonPath: venv.python,
-        bridgeScriptPath: bridgePath.path,
-        timeoutMs,
-        request: {
-          action: params.action,
-          params: { ...params },
-          options: {
-            cwd: options.cwd,
-            palacePath,
-            agentName: options.config.defaultAgentName,
+
+      const invokeOnce = async (): Promise<BridgeDispatchResult> => {
+        const runResult = await runBridge({
+          pythonPath: venv.python,
+          bridgeScriptPath: bridgePath.path,
+          timeoutMs,
+          request: {
+            action: params.action,
+            params: { ...params },
+            options: {
+              cwd: options.cwd,
+              palacePath,
+              agentName: options.config.defaultAgentName,
+            },
           },
-        },
-      });
+        });
+
+        if (!runResult.ok) {
+          return {
+            result: {
+              ok: false,
+              action: params.action,
+              error: withSetupRemediation(runResult.error),
+              diagnostics: {
+                durationMs: runResult.durationMs,
+                stdoutPreview: runResult.stdoutPreview,
+                stderrTail: runResult.stderrTail,
+              },
+            },
+            release: runResult.completion ?? RELEASED,
+          };
+        }
+
+        if (!runResult.response.ok) {
+          return {
+            result: {
+              ok: false,
+              action: params.action,
+              error: withSetupRemediation(runResult.response.error),
+              diagnostics: mergeDiagnostics(runResult.response.diagnostics, {
+                durationMs: runResult.durationMs,
+                stderr: runResult.stderr,
+              }),
+            },
+            release: RELEASED,
+          };
+        }
 
-      if (!runResult.ok) {
         return {
-          ok: false,
-          action: params.action,
-          error: withSetupRemediation(runResult.error),
-          diagnostics: {
-            durationMs: runResult.durationMs,
-            stdoutPreview: runResult.stdoutPreview,
-            stderrTail: runResult.stderrTail,
+          result: {
+            ok: true,
+            action: params.action,
+            result: runResult.response.result ?? {},
+            diagnostics: mergeDiagnostics(runResult.response.diagnostics, {
+              durationMs: runResult.durationMs,
+              stderr: runResult.stderr,
+            }),
           },
+          release: RELEASED,
         };
-      }
+      };
 
-      if (!runResult.response.ok) {
-        return {
-          ok: false,
-          action: params.action,
-          error: withSetupRemediation(runResult.response.error),
-          diagnostics: mergeDiagnostics(runResult.response.diagnostics, {
-            durationMs: runResult.durationMs,
-            stderr: runResult.stderr,
-          }),
+      // dispatch: run with one retry on transient errors for eligible actions.
+      const dispatch = async (): Promise<BridgeDispatchResult> => {
+        const first = await invokeOnce();
+        const withRetries = (r: BridgeDispatchResult, retries: number): BridgeDispatchResult => {
+          const diag = { ...r.result.diagnostics, retries };
+          return {
+            result: r.result.ok
+              ? { ok: true, action: r.result.action, result: r.result.result, diagnostics: diag }
+              : { ok: false, action: r.result.action, error: r.result.error, diagnostics: diag },
+            release: r.release,
+          };
         };
+        if (
+          !first.result.ok &&
+          RETRY_ON_TRANSIENT.has(params.action) &&
+          TRANSIENT_ERROR_CODES.has(first.result.error.code)
+        ) {
+          await first.release;
+          await new Promise<void>((res) => setTimeout(res, 150));
+          return withRetries(await invokeOnce(), 1);
+        }
+        return withRetries(first, 0);
+      };
+
+      // Serialize write actions per palace to avoid ChromaDB lock contention.
+      if (isWriteAction(params.action)) {
+        const mutexKey = canonicalPalaceKey(palacePath);
+        const tail = palaceMutex.get(mutexKey) ?? RELEASED;
+        const mine = tail.then(dispatch, dispatch);
+        // Chaining uses the runtime completion signal, not just the call
+        // result. A bridge_timeout can be returned to the caller before the
+        // killed Python child has fully exited; next writer must wait until
+        // that completion settles so sqlite/Chroma locks are released.
+        const settled = mine
+          .then(({ release }) => release, () => RELEASED)
+          .then(() => {}, () => {});
+        palaceMutex.set(mutexKey, settled);
+        // GC the entry once the release signal settles, if no later writer has
+        // stacked on top. Comparing identity preserves the chain when another
+        // writer enqueued between `set` above and settlement.
+        settled.then(() => {
+          if (palaceMutex.get(mutexKey) === settled) {
+            palaceMutex.delete(mutexKey);
+          }
+        });
+        return (await mine).result;
       }
 
-      return {
-        ok: true,
-        action: params.action,
-        result: runResult.response.result ?? {},
-        diagnostics: mergeDiagnostics(runResult.response.diagnostics, {
-          durationMs: runResult.durationMs,
-          stderr: runResult.stderr,
-        }),
-      };
+      return (await dispatch()).result;
     },
   };
 }

package/src/mempalace/config.ts

@@ -26,13 +26,19 @@ function expandUserPath(input: string, cwd: string): string {
 }
 
 function sanitizedWing(value: string): string {
+  // MemPalace's own normalize_wing_name canonicalizes wing slugs with
+  // underscores (`hyphens` and spaces are folded to `_`). We mirror that
+  // here so a project directory like `sij_mono` and a supipowers-resolved
+  // wing `sij-mono` collapse to the same slug; otherwise data ends up
+  // split across two wings (`sij_mono` vs `sij-mono`) and search/diary
+  // writes diverge between the CLI and the hook bridge.
   return value
     .trim()
     .toLowerCase()
-    .replace(/[\s/\\]+/g, "-")
-    .replace(/[^a-z0-9_-]+/g, "-")
-    .replace(/[-_]+/g, "-")
-    .replace(/^-+|-+$/g, "");
+    .replace(/[\s/\\-]+/g, "_")
+    .replace(/[^a-z0-9_]+/g, "_")
+    .replace(/_+/g, "_")
+    .replace(/^_+|_+$/g, "");
 }
 
 export function normalizeMempalaceWing(value: string): string {