pi-oracle 0.1.12 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+## 0.2.1 - 2026-04-07
+
+### Fixed
+- wake-up guidance now tells receivers to use `oracle_read(jobId)` as the canonical way to consume completion results
+- manual inspection before the first wake-up no longer suppresses the initial reminder attempt
+- wake-up settlement now records provenance so suppressed/settled delivery can be explained in postmortems
+- queued archive cleanup retries now retry queued archive deletion and keep warnings until cleanup succeeds
+- queued archive byte-pressure accounting now includes retained pre-submit archives instead of only currently queued jobs
+
+## 0.2.0 - 2026-04-06
+
+### Added
+- workerless queued oracle jobs with automatic promotion when capacity is available
+- queue position/status reporting and queued-job cancellation
+- durable wake-up target leasing for cross-process completion notification routing
+- oracle now requires a persisted pi session identity instead of collapsing in-memory/no-session contexts onto a shared project-level wake-up target
+- legacy project-scoped jobs from the older no-session model now stay manual/status-only on upgrade instead of being adopted by another persisted session for wake-up delivery
+- lock and lease metadata publication is now atomic on both first publish and rewrites so concurrent wake-up-target reads cannot transiently hide live sessions
+- metadata-less lock/lease state directories left behind by crashes are now reclaimed after a bounded grace instead of wedging future operations forever
+- expanded oracle sanity coverage for queueing, recovery, cancellation, promotion, and notification edge cases
+- a real TypeScript typecheck gate via `npm run typecheck` and `npm run verify:oracle`
+
+### Changed
+- queued jobs now promote using their persisted config snapshot
+- runtime admission now stays blocked when cleanup warnings indicate teardown is incomplete
+- cleanup-driven promotion only advances the queue after a clean runtime teardown
+- orphaned completion wake-ups can be adopted safely when the original session is no longer live
+- oracle completion notifications now avoid synthetic assistant session-history writes entirely and rely on durable job-state response/artifact persistence plus best-effort wake-ups
+
+### Fixed
+- PID-safe worker cancellation and stale-worker recovery paths
+- same-job conversation lease reuse during queued follow-up retries
+- cleanup-warning handling across submit, promotion, cancellation, and terminal cleanup flows
+- queue advancement after cancellation now requires clean teardown
+- cleanup failures no longer silently drop warning state or remove terminal job records prematurely
+- stale notification claimants can no longer finalize completion delivery after ownership handoff
+- best-effort wake-up retries remain bounded without creating synthetic completion messages in session history, including stale cross-session claimant races
+- completed and cancelled jobs now prune on explicit terminal-job retention policy instead of depending on synthetic notification state
+- stale live terminal cleanup workers are now terminated and recovered automatically so cleanup-pending jobs do not wedge capacity indefinitely
+- prune/clean paths now coordinate with in-flight wake-up delivery so already-prunable jobs are skipped, claimed jobs are not deleted before their reminder send path resolves, and just-sent wake-ups keep their response/artifact files briefly retained
+- `/oracle-clean` now refuses terminal jobs whose worker is still live instead of deleting around active cleanup
+- live and off-session completion handling no longer risks corrupting active session history with extension-authored assistant appends
+- `oracle_read` now reports artifact paths from the configured oracle jobs directory instead of hard-coding `/tmp`
+- manual `oracle_read` and `/oracle-status` inspection now settles further wake-up retries so live sessions do not get repeated reminder turns after the job has already been opened

package/README.md

@@ -6,7 +6,9 @@ It exists for the hard cases where you want:
 - the user’s real ChatGPT account
 - web-model behavior instead of API usage
 - large project-context uploads
-- async background execution that wakes the originating `pi` session when done
+- async background execution with durable job-state/response artifacts plus best-effort wake-ups for the originating `pi` session
+- oracle requires a persisted `pi` session identity; in-memory/no-session contexts are rejected instead of risking wrong-session wake-ups
+- legacy project-scoped jobs created before that change remain readable via project status/read commands, but skip best-effort wake-up routing after upgrade
 
 Normal oracle jobs run in an isolated browser profile, not in the user’s active Chrome window.
 
@@ -30,15 +32,16 @@ The extension adds:
 
 An oracle job:
 1. gathers a project archive
-2. opens ChatGPT in an isolated runtime profile
-3. uploads the archive and sends the prompt
-4. waits in the background
-5. persists the response and any artifacts under `/tmp/oracle-<job-id>/`
+2. if runtime capacity is full, persists as `queued` and starts automatically later
+3. otherwise opens ChatGPT in an isolated runtime profile
+4. uploads the archive and sends the prompt
+5. waits in the background
+6. persists the response and any artifacts under the oracle job directory (`${PI_ORACLE_JOBS_DIR:-/tmp}/oracle-<job-id>/` by default)
    - old terminal jobs are later pruned according to cleanup retention settings
    - when directory inputs are expanded, project archives automatically skip common bulky generated caches and top-level build outputs such as `node_modules/`, `target/`, virtualenv caches, coverage outputs, and `dist/`/`build/`/`out/`, unless you explicitly pass those directories
    - whole-repo archive defaults also skip obvious credentials/private data such as `.env` files, key material, credential dotfiles, local database files, and root `secrets/` directories unless you explicitly pass them
    - if a whole-repo archive is still too large after default exclusions, submit automatically prunes the largest nested directories with generic generated-output names like `build/`, `dist/`, `out/`, `coverage/`, and `tmp/` outside obvious source roots like `src/` and `lib/`, and successful submissions report what was pruned
-6. wakes the originating `pi` session on completion
+7. persists the response/artifacts durably in oracle job state and issues best-effort wake-ups to whichever matching `pi` session is currently live
 
 ## Example
 
@@ -61,6 +64,7 @@ Currently validated for:
 - local ChatGPT web login in Chrome
 - isolated auth seed profile + per-job runtime profile clones
 - concurrent jobs across different projects/sessions
+- workerless queued jobs when the global concurrency limit is full
 - same-conversation exclusion for follow-ups
 - plain-text responses
 - artifact capture, including multi-artifact runs
@@ -119,21 +123,30 @@ Common settings:
 Project config should only override safe, non-privileged settings.
 
 Cleanup behavior:
-- terminal job directories under `/tmp/oracle-<job-id>/` are retained for inspection, then pruned conservatively
-- completed/cancelled jobs are pruned after `cleanup.completeJobRetentionMs` once they have been notified
+- terminal job directories under the configured oracle jobs dir (`${PI_ORACLE_JOBS_DIR:-/tmp}/oracle-<job-id>/` by default) are retained for inspection, then pruned conservatively
+- completed/cancelled jobs are pruned after `cleanup.completeJobRetentionMs` based on terminal-job age, but recent wake-up sends keep response/artifact files retained briefly so follow-up turns do not point at deleted paths
 - failed jobs are pruned after `cleanup.failedJobRetentionMs`
-- `/oracle-clean` performs runtime cleanup before removing the job directory and reports cleanup warnings if any residual cleanup step fails
+- `/oracle-cancel` can cancel queued or active jobs
+- `/oracle-clean` refuses non-terminal jobs, including queued ones, refuses terminal jobs whose worker is still live, also refuses recently woken jobs during a short post-send retention grace window, performs runtime cleanup before removing terminal job directories, and reports cleanup warnings if any residual cleanup step fails
 
 Detailed design and maintainer docs:
 - `docs/ORACLE_DESIGN.md`
 - `docs/ORACLE_RECOVERY_DRILL.md`
 
+Completion notification semantics:
+- oracle responses and artifacts are always persisted durably in oracle job state under the configured oracle jobs dir (`${PI_ORACLE_JOBS_DIR:-/tmp}/oracle-<job-id>/` by default)
+- completion delivery into pi sessions is best-effort wake-up based; the extension no longer appends synthetic assistant completion messages into session history
+- wake-up content tells the receiving assistant to call `oracle_read(jobId)` as the canonical completion-consumption path, with saved file paths included as secondary context
+- manual `oracle_read` or `/oracle-status` inspection settles further reminder retries once the terminal job has been opened, and now persists settlement provenance for postmortems
+- manual inspection before the first wake-up attempt is recorded as observation only and does not suppress the first reminder send
+- if a wake-up does not land, the job remains available via its saved response/artifacts and status commands
+
 ## Privacy / local data
 
 This extension is local-first, but it does read and persist local data:
 - `/oracle-auth` reads ChatGPT cookies from a local Chrome profile
 - job archives are uploaded to ChatGPT.com
-- responses and artifacts are written under `/tmp/oracle-<job-id>/`
+- responses and artifacts are written under the configured oracle jobs dir (`${PI_ORACLE_JOBS_DIR:-/tmp}/oracle-<job-id>/` by default)
 
 Review the code and design docs before using it with sensitive material.
 
@@ -141,8 +154,11 @@ Review the code and design docs before using it with sensitive material.
 
 ```bash
 npm run check:oracle-extension
+npm run typecheck
 npm run sanity:oracle
 npm run pack:check
+# or all at once
+npm run verify:oracle
 ```
 
 ## Beta caveats