pi-oracle 0.3.4 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.4.0 - 2026-04-12
+
+### Added
+- repeatable isolated local-extension `pi` validation guidance for oracle release verification, including smoke workflows that load the in-repo extension source directly
+- persisted oracle lifecycle-event breadcrumbs plus richer detached-job observability in `oracle_submit`, `oracle_read`, poller wake-ups, and `/oracle-status`, including worker-log paths and last-event context
+- shared worker/auth validation helpers, shared concurrency primitives, shared lifecycle reducers, and shared observability formatters to keep extension and worker behavior aligned
+- extracted sanity-harness support and poller suites with typed helper scaffolding and repeated-run stability coverage
+
+### Changed
+- oracle whole-repo archiving now excludes local tool state like `.pi/`, `.oracle-context/`, `.cursor/`, and `.scratchpad.md` by default while preserving explicitly requested paths
+- lock/lease recovery, queue promotion, process identity handling, and lifecycle transitions now flow through shared helper modules instead of duplicated inline implementations
+- worker/auth verification now leans on behaviorally tested helper modules plus dedicated `typecheck:worker-helpers` coverage instead of syntax checks and brittle source-string assertions alone
+- release validation now expects isolated local-extension `pi` smoke tests and a stronger local oracle verification gate before shipping
+
+### Fixed
+- archive input resolution now rejects symlink escapes outside the repo root and preserves safer repo-boundary handling for targeted archives
+- hung `tar`, `zstd`, `cp`, and auth `agent-browser` subprocesses now time out and fail clearly instead of wedging archive, runtime-clone, or auth flows indefinitely
+- cleanup warnings without a live worker no longer consume runtime/conversation capacity forever, while teardown still attempts lease release and preserves warnings for later triage
+- detached oracle workers and poller flows now report clearer lifecycle breadcrumbs, wake-up settlement state, and failure context during fast-fail auth/bootstrap scenarios
+- sanity-runner cleanup now retries transient temp-directory removal races, and the extracted harness is less timing-fragile and less `any`-driven than the previous monolithic runner
+
 ## 0.3.4 - 2026-04-11
 
 ### Changed

package/README.md

@@ -195,6 +195,7 @@ Project config should only override safe, non-privileged settings.
 
 - `docs/ORACLE_DESIGN.md` — architecture, lifecycle, queueing, persistence, presets, and recovery behavior
 - `docs/ORACLE_RECOVERY_DRILL.md` — safe expired-auth recovery validation drill
+- `docs/ORACLE_ISOLATED_PI_VALIDATION.md` — repeatable isolated `pi` session smoke test for local-extension validation
 
 ## Privacy / local data
 
@@ -210,6 +211,7 @@ Review the code and design docs before using it with sensitive material.
 ```bash
 npm run check:oracle-extension
 npm run typecheck
+npm run typecheck:worker-helpers
 npm run sanity:oracle
 npm run pack:check
 # conventional local gate

package/docs/ORACLE_ISOLATED_PI_VALIDATION.md

@@ -0,0 +1,249 @@
+# Oracle isolated `pi` validation
+
+This document describes the repeatable pre-commit smoke test for validating `pi-oracle` through isolated `pi` agent sessions that load the local extension source.
+
+Use this workflow for code changes when you need end-to-end evidence beyond `npm test`.
+
+## What this validates
+
+- the local extension can be loaded directly by isolated `pi` sessions
+- whole-repo `oracle_submit` archive creation excludes local tool state by default
+- targeted archive inputs cannot escape the repo through symlinked paths
+- the exercised `pi` agents can provide candid feedback about tool clarity or clunkiness
+
+## Why this workflow is isolated
+
+The test intentionally uses separate directories for:
+
+- `PI_CODING_AGENT_DIR`
+- `--session-dir`
+- `PI_ORACLE_JOBS_DIR`
+
+That keeps the validation run from reusing your normal `pi` agent state.
+
+The extension is loaded from the local checkout with:
+
+```bash
+pi --no-extensions -e "$REPO/extensions/oracle/index.ts"
+```
+
+That ensures the session is exercising the in-repo code, not a globally installed package.
+
+## Preset requirement
+
+Use either:
+
+- `instant`
+- `thinking_light`
+
+The examples below use `instant` because it is the fastest smoke-test preset.
+
+## Prerequisites
+
+- `pi` installed locally
+- `tmux` installed locally
+- run from the repository root
+
+## Repeatable smoke test
+
+```bash
+set -euo pipefail
+
+REPO="$PWD"
+TEST_ROOT="/tmp/pi-oracle-isolated-tests-$$"
+
+TEST1_AGENT="$TEST_ROOT/agent1"
+TEST1_SESSIONS="$TEST_ROOT/sessions1"
+TEST1_JOBS="$TEST_ROOT/jobs1"
+TEST2_AGENT="$TEST_ROOT/agent2"
+TEST2_SESSIONS="$TEST_ROOT/sessions2"
+TEST2_JOBS="$TEST_ROOT/jobs2"
+
+FIXTURE="$TEST_ROOT/symlink-fixture"
+OUTSIDE="$TEST_ROOT/outside"
+
+SESSION1="pi-oracle-test1"
+SESSION2="pi-oracle-test2"
+
+mkdir -p \
+  "$TEST1_AGENT" "$TEST1_SESSIONS" "$TEST1_JOBS" \
+  "$TEST2_AGENT" "$TEST2_SESSIONS" "$TEST2_JOBS" \
+  "$FIXTURE" "$OUTSIDE"
+
+echo 'secret' > "$OUTSIDE/secret.txt"
+ln -s "$OUTSIDE" "$FIXTURE/linked-outside"
+
+PROMPT1='Call oracle_submit directly with prompt "Sanity test for archive exclusions. Reply with OK." files ["."] and preset "instant". Do not use bash. After the tool returns, summarize the outcome in 3 bullets including the job id/status, and give one sentence of candid feedback on whether the oracle tool behavior feels clear or clunky.'
+PROMPT2='Call oracle_submit directly with prompt "Sanity test for symlink escape rejection." files ["linked-outside/secret.txt"] and preset "instant". Do not use bash. After the tool returns, summarize the outcome in 3 bullets and give one sentence of candid feedback on whether the oracle tool behavior feels clear or clunky.'
+
+cleanup() {
+  tmux kill-session -t "$SESSION1" 2>/dev/null || true
+  tmux kill-session -t "$SESSION2" 2>/dev/null || true
+}
+trap cleanup EXIT
+cleanup
+
+TMUX_CMD1="cd '$REPO' && env PI_CODING_AGENT_DIR='$TEST1_AGENT' PI_ORACLE_JOBS_DIR='$TEST1_JOBS' PATH='$PATH' pi --session-dir '$TEST1_SESSIONS' --no-extensions -e '$REPO/extensions/oracle/index.ts'"
+tmux new-session -d -s "$SESSION1" "$TMUX_CMD1"
+sleep 8
+tmux send-keys -t "$SESSION1":0.0 "$PROMPT1" Enter
+sleep 35
+
+echo '--- pane:test1'
+tmux capture-pane -p -S -220 -t "$SESSION1":0.0 | tail -n 160
+
+JOB_DIR1="$(find "$TEST1_JOBS" -maxdepth 1 -type d -name 'oracle-*' | sort | tail -n 1 || true)"
+echo "--- latest job dir:test1 ${JOB_DIR1:-<none>}"
+
+if [ -n "${JOB_DIR1:-}" ] && [ -f "$JOB_DIR1/job.json" ]; then
+  ARCHIVE1="$(python3 - <<'PY' "$JOB_DIR1/job.json"
+import json,sys
+with open(sys.argv[1]) as f:
+    print(json.load(f)['archivePath'])
+PY
+)"
+  echo "--- archive:test1 $ARCHIVE1"
+  tar --zstd -tf "$ARCHIVE1" | head -n 80
+  LIST="$(mktemp)"
+  tar --zstd -tf "$ARCHIVE1" > "$LIST"
+  for path in .pi/settings.json .oracle-context .cursor .scratchpad.md README.md; do
+    if grep -E -q "^${path}$|^${path}/" "$LIST"; then
+      echo "FOUND $path"
+    else
+      echo "MISSING $path"
+    fi
+  done
+  rm -f "$LIST"
+fi
+
+TMUX_CMD2="cd '$FIXTURE' && env PI_CODING_AGENT_DIR='$TEST2_AGENT' PI_ORACLE_JOBS_DIR='$TEST2_JOBS' PATH='$PATH' pi --session-dir '$TEST2_SESSIONS' --no-extensions -e '$REPO/extensions/oracle/index.ts'"
+tmux new-session -d -s "$SESSION2" "$TMUX_CMD2"
+sleep 8
+tmux send-keys -t "$SESSION2":0.0 "$PROMPT2" Enter
+sleep 25
+
+echo '--- pane:test2'
+tmux capture-pane -p -S -220 -t "$SESSION2":0.0 | tail -n 160
+
+echo '--- jobs created:test2'
+find "$TEST2_JOBS" -maxdepth 1 -type d -name 'oracle-*' | sort || true
+
+echo "TEST_ROOT=$TEST_ROOT"
+```
+
+## Expected results
+
+### Test 1: whole-repo archive exclusions
+
+Expected behavior:
+
+- the isolated `pi` session loads the local extension successfully
+- `oracle_submit` creates a job and an archive path under the isolated jobs dir
+- the archive should exclude:
+  - `.pi/`
+  - `.oracle-context/`
+  - `.cursor/`
+  - `.scratchpad.md`
+- the archive should still include normal repo files such as `README.md`
+
+Notes:
+
+- this smoke test does not require `/oracle-auth`
+- without an auth seed profile, the worker fails after archive creation, which is useful because the archive remains on disk for inspection
+
+### Test 2: symlink escape rejection
+
+Expected behavior:
+
+- `oracle_submit` rejects `linked-outside/secret.txt`
+- the error should say the archive input must resolve inside the project cwd without symlink escapes
+- no oracle job directory should be created for the rejected submit
+
+## Additional failure-mode smoke tests
+
+### `/oracle-auth` should fail fast when `agent-browser` hangs
+
+Use this when validating timeout hardening around auth/bootstrap browser commands.
+
+```bash
+set -euo pipefail
+
+REPO="$PWD"
+TEST_ROOT="/tmp/pi-oracle-auth-timeout-$$"
+AGENT_DIR="$TEST_ROOT/agent"
+SESSION_DIR="$TEST_ROOT/sessions"
+JOBS_DIR="$TEST_ROOT/jobs"
+FAKE_BROWSER="$TEST_ROOT/agent-browser"
+SESSION_NAME="pi-oracle-auth-timeout"
+
+mkdir -p "$AGENT_DIR/extensions" "$SESSION_DIR" "$JOBS_DIR"
+
+cat > "$AGENT_DIR/extensions/oracle.json" <<JSON
+{
+  "auth": {
+    "chromeCookiePath": "$TEST_ROOT/missing-cookies.sqlite"
+  }
+}
+JSON
+
+cat > "$FAKE_BROWSER" <<'SH'
+#!/bin/sh
+trap 'exit 0' TERM INT
+while :; do sleep 1; done
+SH
+chmod +x "$FAKE_BROWSER"
+
+cleanup() {
+  tmux kill-session -t "$SESSION_NAME" 2>/dev/null || true
+}
+trap 'cleanup; rm -rf "$TEST_ROOT"' EXIT
+cleanup
+
+TMUX_CMD="cd '$REPO' && env PI_CODING_AGENT_DIR='$AGENT_DIR' PI_ORACLE_JOBS_DIR='$JOBS_DIR' AGENT_BROWSER_PATH='$FAKE_BROWSER' PI_ORACLE_AUTH_AGENT_BROWSER_TIMEOUT_MS='250' PI_ORACLE_AUTH_CLOSE_TIMEOUT_MS='250' PI_ORACLE_AUTH_KILL_GRACE_MS='100' PATH='$PATH' pi --session-dir '$SESSION_DIR' --no-extensions -e '$REPO/extensions/oracle/index.ts'"
+
+tmux new-session -d -s "$SESSION_NAME" "$TMUX_CMD"
+sleep 8
+tmux send-keys -t "$SESSION_NAME":0.0 '/oracle-auth' Enter
+sleep 12
+
+tmux capture-pane -p -S -220 -t "$SESSION_NAME":0.0 | tail -n 140
+```
+
+Expected behavior:
+
+- the isolated `pi` session loads the local extension successfully
+- `/oracle-auth` returns with an error instead of hanging indefinitely
+- the output should mention the missing ChatGPT session-token cookies or the configured cookie source problem
+- the session should remain usable after the command failure
+
+## Switching to `thinking_light`
+
+To run the same smoke test with `thinking_light`, change both prompts from:
+
+```text
+preset "instant"
+```
+
+to:
+
+```text
+preset "thinking_light"
+```
+
+## Cleanup
+
+The snippet already kills the temporary `tmux` sessions on exit.
+
+To remove the temporary files after inspection:
+
+```bash
+rm -rf "$TEST_ROOT"
+```
+
+## Minimum pre-commit evidence
+
+Before committing code changes, keep evidence for:
+
+- `npm test` passing
+- isolated `pi` session validation using this workflow
+- any agent feedback gathered during the isolated run if it exposed clunky or unclear behavior

package/extensions/oracle/index.ts

@@ -1,3 +1,8 @@
+// Purpose: Register the oracle extension, wire commands/tools/workers, and manage per-session background maintenance.
+// Responsibilities: Bootstrap oracle commands and tools, start or stop polling, and surface startup/config availability in the pi session UI.
+// Scope: Extension entrypoint only; lifecycle mutation lives in lib modules and browser execution lives in worker scripts.
+// Usage: Loaded by pi as the extension module declared in package.json.
+// Invariants/Assumptions: Oracle only runs against persisted sessions, and startup maintenance should be best-effort without breaking session initialization.
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
@@ -42,7 +47,9 @@ export default function oracleExtension(pi: ExtensionAPI) {
 
       const config = loadOracleConfig(ctx.cwd);
       void runStartupMaintenance(ctx).catch((error) => {
-        console.error("Oracle startup maintenance failed:", error);
+        const message = `Oracle startup maintenance failed: ${error instanceof Error ? error.message : String(error)}`;
+        console.error(message);
+        ctx.ui.notify(message, "warning");
       });
       startPoller(pi, ctx, config.poller.intervalMs, workerPath);
       refreshOracleStatus(ctx);

package/extensions/oracle/lib/commands.ts

@@ -1,8 +1,15 @@
+// Purpose: Register slash commands for oracle auth/bootstrap, status inspection, cancellation, and cleanup.
+// Responsibilities: Bridge command handlers to shared oracle lifecycle helpers, surface consistent summaries, and coordinate follow-up queue advancement.
+// Scope: Command-facing orchestration only; durable lifecycle mutations live in jobs/runtime/tools modules and browser execution stays in worker scripts.
+// Usage: Imported by the oracle extension entrypoint to register /oracle-* commands with pi.
+// Invariants/Assumptions: Commands operate on persisted project-scoped jobs and rely on shared observability formatting for detached-state clarity.
 import { spawn } from "node:child_process";
 import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import { formatOracleJobSummary } from "../shared/job-observability-helpers.mjs";
 import { loadOracleConfig } from "./config.js";
 import {
   cancelOracleJob,
+  getJobDir,
   isOpenOracleJob,
   isTerminalOracleJob,
   listJobsForCwd,
@@ -22,30 +29,10 @@ function summarizeJob(jobId: string): string {
   const job = readJob(jobId);
   if (!job) return `Oracle job ${jobId} not found.`;
 
-  const queuePosition = job.status === "queued" ? getQueuePosition(job.id) : undefined;
-  return [
-    `job: ${job.id}`,
-    `status: ${job.status}`,
-    `phase: ${job.phase}`,
-    `created: ${job.createdAt}`,
-    job.queuedAt ? `queued: ${job.queuedAt}` : undefined,
-    job.submittedAt ? `submitted: ${job.submittedAt}` : undefined,
-    queuePosition ? `queue-position: ${queuePosition.position} of ${queuePosition.depth} global` : undefined,
-    `project: ${job.projectId}`,
-    `session: ${job.sessionId}`,
-    job.completedAt ? `completed: ${job.completedAt}` : undefined,
-    job.followUpToJobId ? `follow-up-to: ${job.followUpToJobId}` : undefined,
-    job.chatUrl ? `chat: ${job.chatUrl}` : undefined,
-    job.conversationId ? `conversation: ${job.conversationId}` : undefined,
-    job.responsePath ? `response: ${job.responsePath}` : undefined,
-    job.responseFormat ? `response-format: ${job.responseFormat}` : undefined,
-    typeof job.artifactFailureCount === "number" ? `artifact-failures: ${job.artifactFailureCount}` : undefined,
-    job.lastCleanupAt ? `last-cleanup: ${job.lastCleanupAt}` : undefined,
-    job.cleanupWarnings?.length ? `cleanup-warnings: ${job.cleanupWarnings.join(" | ")}` : undefined,
-    job.error ? `error: ${job.error}` : undefined,
-  ]
-    .filter(Boolean)
-    .join("\n");
+  return formatOracleJobSummary(job, {
+    queuePosition: job.status === "queued" ? getQueuePosition(job.id) : undefined,
+    artifactsPath: `${getJobDir(job.id)}/artifacts`,
+  });
 }
 
 function getLatestJobId(cwd: string): string | undefined {

package/extensions/oracle/lib/config.ts

@@ -1,3 +1,8 @@
+// Purpose: Define oracle configuration schema, defaults, preset selection, and local config loading behavior.
+// Responsibilities: Normalize preset ids, load extension config from disk, expose default browser/auth/runtime settings, and validate config shape.
+// Scope: Configuration and preset resolution only; runtime/job execution stays in sibling oracle modules.
+// Usage: Imported by oracle tools, commands, runtime helpers, and sanity tests when config or preset resolution is required.
+// Invariants/Assumptions: Preset ids remain the canonical model-selection contract and config loading must fail clearly on invalid user overrides.
 import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";