pwn 0.5.782 → 0.5.784

data/documentation/diagrams/dot/cron-scheduling.dot

@@ -16,7 +16,7 @@ digraph "PWN_Cron" {
 
   Jobs    [label="~/.pwn/cron/jobs.yml", shape=cylinder, fillcolor="#fcd34d"];
   Crontab [label="per-job crontab\n(install_crontab: true)", fillcolor="#fda4af"];
-  Worker  [label="background worker\npwn setup keep-alive\nsystemd --user / launchd\nschtasks / crontab @reboot", fillcolor="#fda4af"];
+  Worker  [label="background worker\npwn setup starts/reuses\nportable internal scheduler\nhousekeeping: never systemd", fillcolor="#fda4af"];
   Runner  [label="PWN::Cron.run(id)", fillcolor="#c4b5fd"];
 
   subgraph cluster_kinds {
@@ -29,7 +29,7 @@ digraph "PWN_Cron" {
   {rank=same; Prompt; Ruby; Script}
 
   subgraph cluster_seed {
-    label="Seeded Jobs (install_defaults)"; fontcolor="#ddd6fe"; style=rounded;
+    label="Optional curriculum templates / preserved legacy jobs (NOT seeded)"; fontcolor="#ddd6fe"; style=rounded;
     color="#6d28d9"; bgcolor="#2e1065"; penwidth=2;
     Practice [label="curriculum_practice_nightly\n0 3 * * *  OFF\nCurriculum.practice(limit:3)", fillcolor="#c4b5fd"];
     Offline  [label="curriculum_offline_judge\n30 3 * * *  OFF\nCurriculum.offline_judge", fillcolor="#c4b5fd"];
@@ -39,7 +39,7 @@ digraph "PWN_Cron" {
   }
   {rank=same; Practice; Offline; Train; MemGC; Lean}
 
-  Cleanup [label="session_cleanup\n45 3 * * * ON\nleases / pins / backup before delete", fillcolor="#c4b5fd"];
+  Cleanup [label="ONLY fresh default: session_cleanup\n45 3 * * * ON (first-slot guard)\nevidence-first maintenance\nthen memory consolidation\nthen learning / mistakes / policy retention", fillcolor="#c4b5fd"];
   Ruby -> Cleanup; Cleanup -> Log;
   Log [label="~/.pwn/cron/log/<id>.log\nlast_run · last_status", shape=cylinder, fillcolor="#fcd34d"];
 

data/documentation/pwn-REPL.md

@@ -45,9 +45,37 @@ Aliases shared by multiple sessions are ambiguous too; use a stable ID.
 `dependencies` means **referenced by**: files containing defined structural
 references to that session. Transcript prose, prompts, tool results and quoted
 JSON—including previous `/sessions list` output—are not dependencies. An empty
-array means no known structural references; `dependency_errors` separately
-reports uncertainty and blocks scheduled cleanup. Dependency-backed sessions
-stay visible and resumable. See Installation's session-cleanup schema table.
+array means no known structural references. `dependency_errors` contains only
+errors attributed to this session; `unresolved_dependency_stores` reports global
+uncertainty without assigning blame. Lists always include the current active
+session, even while its title is provisional or summary generation failed.
+Other rows require valid summary provenance or valid structural dependencies.
+This display exception does not confer summary provenance or bypass cleanup:
+activity leases still prevent physical deletion. Explicit resume remains available.
+`/sessions list [offset] [limit]` defaults to the newest page, ordered oldest-first
+within that page. An explicit offset starts at that oldest-first position.
+The current session is marked `active: true` and included once even outside the
+requested page (so at most limit + 1 rows). `total` counts unique visible sessions;
+`offset` and `has_more` describe the base page, not the extra active row.
+Global unresolved stores and specific diagnostics are reported once in the envelope.
+Title workers capture the active provider/model when the request starts, summarize
+only that session's persisted conversation, and retry on resume. Pending work is
+coalesced per session rather than dropping another session's update. Failed or
+invalid generation keeps the previous title and cursor, and reports a warning
+without exposing provider payloads. It never fabricates `title_source: summary`.
+`/sessions cleanup` applies the bundled cron maintenance operation; use
+`/sessions cleanup --dry-run` for a read-only preview. Migration preserves full
+redacted learning snapshots and their offline readers; it does not manufacture
+lossless migrations for other stores. Unknown global ownership blocks apply.
+Prepared/committed maintenance ledgers and recoverable backups live outside
+ordinary backup pruning. Old writers must be quiesced before live deployment;
+updating a helper alone does not update a running process.
+Request checkpoints use a version-1, hash-bound identity adapter: their session
+field is provenance because restore consumes the checkpoint itself. Unknown
+versions, fields and mismatched paths remain unresolved; checkpoint bytes are
+never rewritten by cleanup. Other unmigrated evidence edges remain retained.
+`Sessions.list(include_hidden: true)` is the diagnostic inventory. See
+Installation's session-cleanup schema table and remediation limitations.
 `title_source`, `is_summarized`, `classification` and `title_reason` expose the
 same strict provenance used by cleanup. Only persisted `summary` provenance with
 a nonblank summary/title and positive integer summary cursor counts as named.

data/documentation/pwn-ai-Agent.md

@@ -39,8 +39,68 @@ The curses console exposes these local views through the command menu:
   Running phase checkpoints are atomically persisted before publication, including
   actual check records, uncovered requirements and repair reasons.
   Worktrees isolate edits, **not** arbitrary code execution or network access.
-* `/sessions cleanup` previews the same provenance/dependency policy as scheduled
-  cleanup. Inspect the exact IDs, paths, fingerprints, retention reasons and
+* `/sessions list [offset] [limit]` is a page, not a retention limit. The
+  envelope reports `returned`, visible `total`, `physical_sessions`,
+  `filtered_sessions`, `has_previous` and `has_more`, plus a disjoint root-entry
+  `storage` breakdown. Filtered transcripts remain physically retained and explicitly
+  resumable. Neither pagination nor layout migration deletes summarized sessions.
+* Offline housekeeping migration is separate from ordinary cleanup. After deploying
+  matching source and stopping **all** launchers, workers and cron schedulers, run
+  from the checkout:
+
+  ```ruby
+  require 'pwn'
+  require './etc/default_cron/session_cleanup'
+  PWN::SessionCleanup.reorganize # metadata-only plan; no changes
+  PWN::SessionCleanup.reorganize(dry_run: false, writers_stopped: true)
+  PWN::SessionCleanup.run(dry_run: true) # inspect remaining retention categories
+  # Only after reviewing the ledger and approving cleanup:
+  PWN::SessionCleanup.run(dry_run: false)
+  ```
+
+  Launch Ruby with `bundle exec ruby -Ilib` so this uses matching source, not an
+  older installed gem. `writers_stopped` is an operator assertion, not a way to
+  bypass held leases or unknown legacy owners. Backups and prepared/committed
+  ledgers live in private `~/.pwn/session_cleanup_archive` directories. The layout
+  migration moves unreferenced metadata and lease inodes under `sessions/support`;
+  new trace support also uses that layout. Existing trace paths and dependency-backed
+  metadata stay at their exact locations to preserve evidence anchors and are
+  reported in `retained_support`. Canonical transcripts stay at the root. Abandoned numeric-PID transcript temp
+  files are removed only after exact recoverable backups in this offline operation.
+  Held own-process capability markers stay in place; other active owners block.
+  Readers accept legacy and compact paths, including partially completed moves.
+  Do not restart old binaries after applying the layout. Unknown files, mesh
+  mappings and request checkpoints remain untouched. Complete policy trajectories
+  are self-contained training provenance, not transcript-retention edges; incomplete
+  legacy trajectories and other unresolved evidence consumers still retain sources.
+* Historical IDs are not automatically transcript dependencies. The shared index
+  validates self-contained Mistakes records (error/fix/counters), Memory reflection
+  values, Extrospection drift observations and Curriculum practice results before
+  treating their session IDs as provenance. These stores are not rewritten or
+  deleted by this classification. Incomplete records still pin their identified
+  source; malformed containers remain diagnostics. No summary or training label
+  is invented. Mistakes' previous-turn readers and Memory's session-turn reader
+  operate on the caller's current session, not historical occurrence IDs.
+  Curriculum's practice log is an audit log, not a replay/evaluation queue.
+* Actual Learning transcript consumers retain full redacted, content-addressed
+  evidence through the existing migration before transcript deletion. Sessions.load,
+  Curriculum.offline_judge discovery and Reward PRM copy-on-write annotation use
+  the verified evidence; source hashes and complete source equality are checked
+  before releasing a live transcript. Overlapping provenance records no longer
+  prevent that preservation/re-index/deletion transaction.
+* Swarm `personas.json` is different: `Swarm.ask` calls `persona_session`, which
+  reuses its ID and acquires a writable-session lease for `Loop.run`. `retire`
+  removes an agents.yml registration, not that association; an explicit persona
+  or later respawn can reuse it. There is no persisted association-completed or
+  retired-session marker. Neither old mtime, an absent registry name nor a
+  completed bus message proves a map obsolete. Such mappings remain protected,
+  even with a Learning snapshot, because a read-only training artifact is not a
+  writable continuation. Cleanup does not silently archive them or impose a cap.
+* `/sessions cleanup` runs the same maintenance operation as bundled cron:
+  validate, preserve supported learning evidence, remediate attributable invalid
+  records with recoverable backups, re-index, and remove eligible inactive sessions.
+  `/sessions cleanup --dry-run` previews without changing evidence or deleting
+  sessions. Inspect the exact IDs, paths, fingerprints, retention reasons and
   uncertainty. `a`, then Enter confirms only the displayed candidate set.
   Newly discovered or changed records are excluded. Apply rechecks activity,
   references and source bytes under locks, backs up candidate bytes, and reports