@1aboveio/skills 1.0.18 → 1.0.20

package/skills/engineering/resolve-issues/references/retention.md

@@ -0,0 +1,162 @@
+# Daily resource retention
+
+Keep run history and reclaim explicitly owned, reconstructable generated resources.
+Enrollment belongs to the repository where `resolve-issues` or `rush-issues` is invoked;
+it never discovers or enrolls sibling projects.
+
+## Enroll at preflight
+
+Use the persistent installed skill copy and canonical main checkout:
+
+```bash
+node <skill-base-dir>/scripts/daily-cleanup.mjs install --repo <repo-root>
+```
+
+Repeat enrollment on each invocation to refresh the same job, including after a
+skill or Node update. The installer prefers the stable PATH alias for its current
+Node runtime. The skill directory must remain available; a temporary checkout or
+unpack directory is not an installation.
+
+macOS runs a user LaunchAgent every 12 hours and at load. Linux uses a persistent
+user systemd daily timer with boot catch-up. The scheduler must be available; it
+does not wake a powered-off machine. Report an unsupported host or failed enrollment
+as "daily cleanup not enabled" and continue the issue workflow. A saved job file
+alone does not prove that the job is loaded.
+
+```bash
+node <skill-base-dir>/scripts/daily-cleanup.mjs plan --repo <repo-root>
+node <skill-base-dir>/scripts/daily-cleanup.mjs uninstall --repo <repo-root>
+```
+
+## Preserve records; register resources
+
+Keep plans, source requirements, decisions, findings, results, review verdicts,
+progress and retry history, checkpoints, Git metadata, unpublished work, required
+evidence and credentials. A directory name or an old timestamp proves no authority.
+Whole-workspace cleanup still follows [the delivered-unit lifecycle](workspaces.md#cleanup-after-delivery-before-finish).
+
+The default age floors are seven full days for generated resources and 30 full
+days for explicitly disposable raw artifacts. Recorded activity authorizes the age
+calculation; newer filesystem writes can only postpone removal. Eligible targets
+are ranked by measured allocation, largest first. Shared blocks, hardlinks and local
+filesystem snapshots mean allocation removed is not necessarily free space gained.
+Report the two measurements separately. Removing OS backup snapshots is a separate,
+explicitly authorized operation, never part of this scheduler.
+
+The manifest `<repo>/.resolve-issues/retention.json` binds each resource to its
+run/unit, exact path and filesystem identity, activity, reconstruction recipe and
+explicit registration. Register only paths already owned by the task plan. A
+legacy path needs explicit ownership reconciliation first; inventory never adopts it.
+
+Registration records inventory; it does not release an unfinished owner's resource
+for deletion. Declare each generated resource's `retention` intent in the task plan
+as described in [workspaces.md](workspaces.md#what-the-plan-records). Register the
+ready declarations in one operation before worker admission:
+
+```bash
+node <skill-base-dir>/scripts/retention.mjs register-owned \
+  --repo <repo-root> --run <absolute-run> --unit <unit-id> \
+  --last-used-at <current-ISO-timestamp> --apply --json
+```
+
+Without `--apply`, this previews registration and writes nothing. The command
+considers only `lifecycle.resources` and their retention intent; legacy top-level
+resource lists require explicit reconciliation. It never discovers neighboring
+paths. Exit 0 means complete coverage, 1 means deferred or uncovered resources,
+and 2 means the call was refused. Record its registered, deferred and uncovered results.
+Refresh activity before reuse and repeat registration for newly populated resources
+after their producing worker has settled. Keep that worker's resource report with
+its result. A refusal means the resource remains unregistered; a loaded daily job
+does not mean that every generated environment is covered.
+
+```bash
+node <skill-base-dir>/scripts/retention.mjs register \
+  --repo <repo-root> --run <absolute-run> --unit <unit-id> \
+  --path <absolute-generated-child> --kind generated \
+  --last-used-at <ISO-timestamp> --recipe '<reconstruction instructions>' --json
+```
+
+A resource containing credentials, private configuration, unique scripts or required
+proof is retained. Malformed required-evidence declarations also retain candidates;
+fix the ownership/evidence record rather than ignoring it. Registration and every
+apply pass check these boundaries. Explicitly optional evidence is not a required pin.
+
+For an unfinished task, use `--release-owner` only after explicit resource release
+has been authorized and its reconstruction inputs remain available. It releases the
+resource, not the task or source. Re-registering before reuse withdraws that release;
+an existing pin remains pinned.
+
+## Verify generated formats and rebuild inputs
+
+Use `generic` for explicitly classified caches without a supported format. Its
+conservative metadata and link checks remain in force. A supported generated format
+can distinguish installed package source directories from the run's own source:
+
+| Format | Positive proof | Retained reconstruction inputs |
+| --- | --- | --- |
+| `pnpm-install` | pnpm installation metadata and virtual store | `package.json`, `pnpm-lock.yaml` |
+| `pnpm-store` | versioned content-addressed package store | `package.json`, `pnpm-lock.yaml` |
+| `uv-venv` | virtual-environment configuration, interpreter and installed-package layout | `pyproject.toml`, `uv.lock` |
+| `next-build` | Next.js build output markers | `package.json`, `pnpm-lock.yaml` |
+
+Supply the format and actual input paths explicitly. The inputs must be canonical
+regular files outside the disposable target. The registration records their identity
+and content hashes; changed or uncertain inputs require reassessment. Format proof
+does not exempt credentials, nested Git, run metadata, required evidence or ownership
+checks. Links in a verified generated installation are references: removal unlinks
+them and preserves their destinations.
+
+```bash
+node <skill-base-dir>/scripts/retention.mjs register \
+  --repo <repo-root> --run <absolute-run> --unit <unit-id> \
+  --path <workspace>/node_modules --kind generated --format pnpm-install \
+  --input <workspace>/package.json --input <workspace>/pnpm-lock.yaml \
+  --last-used-at <ISO-timestamp> --recipe 'pnpm install --frozen-lockfile' --json
+```
+
+## Check before reuse
+
+Before admitting a worker that needs a registered resource, inspect its state:
+
+```bash
+node <skill-base-dir>/scripts/retention.mjs status \
+  --repo <repo-root> --run <absolute-run> --unit <unit-id> --json
+```
+
+Read `rebuildRequired`, the reason and retained recipe. A pin or protected credential
+can prevent deletion without making a valid installation need reconstruction.
+Readiness and cleanup eligibility are separate. A missing tree, changed
+reconstruction inputs or a partial installation is not ready merely because its
+parent directory exists. This includes environments left with protected credential
+or configuration fragments after an explicitly authorized manual cleanup.
+
+An unregistered or legacy resource has no readiness proof from this command. Read
+its prior cleanup receipts and verify the repository's install/build contract before
+reuse; do not infer readiness from an empty status result.
+
+Reconstruct with the repository's retained lockfile and existing install/build
+contract before continuing. Preserve protected files at their original paths; do
+not run a clear/reset command that would discard them. Do not execute an arbitrary
+recipe from an untrusted manifest. Verify the reconstructed format and then
+re-register its new identity and current activity without `--release-owner`.
+Until those steps pass, the dependent worker waits and the task stays unfinished.
+
+## Preview, apply and recover
+
+```bash
+node <skill-base-dir>/scripts/retention.mjs plan --repo <repo-root> --json
+node <skill-base-dir>/scripts/retention.mjs apply --repo <repo-root> --apply --json
+node <skill-base-dir>/scripts/retention.mjs recover --repo <repo-root> --json
+```
+
+Apply locks retention and rechecks owner activity, claims, required evidence, source,
+filesystem identity and process use before each removal. Receipts live outside the
+target under `.resolve-issues/retention-receipts`. A partial removal is a failure;
+preserve both the original failure and cleanup errors.
+
+Recovery is read-only by default. `recover --apply` may clear only a lock whose
+record proves its owner is dead on this host. Live, foreign, unreadable, legacy or
+ambiguous locks stay. The daily apply path can make the same proven-dead-owner
+recovery. It never breaks a lock by age. An interrupted receipt or quarantined tree
+remains visible for reconciliation; releasing its dead lock does not declare its
+cleanup complete or remove the quarantined data.

package/skills/engineering/resolve-issues/references/review.md

@@ -8,6 +8,13 @@ restate its rules in the brief beyond the two below.
 
 ## Brief
 
+- Start a fresh reviewer conversation after each completed review round; the existing
+  scope script still chooses delta/full/skip, so freshness adds no review round or test
+  campaign. Give it retained records and code evidence as claims to verify, not an
+  implementer transcript. Launch it normally and keep its attempt reference as
+  `reviewSession`, separate from `implementationOwner`, so an unfinished same-HEAD round
+  can continue in that saved conversation; `retain_session` is optional protection, not
+  what makes it continuable. A round after a completed review is a fresh conversation.
 - Reviewer model: a different id from the implementer's
   ([preflight.md](preflight.md#1-model-slots)). Launch the reviewer with the
   plan's recorded reviewer fill — its `launch`, `instructions`, `selection` and
@@ -119,9 +126,23 @@ the unfinished work rather than repeating the whole assignment; preserve complet
 valid passes. A wrong HEAD or invalid scope must be corrected, not carried as
 completed proof.
 
+On Pi, use `subagent_resume({id: reviewSession.runId, prompt: <unfinished work>})`
+when that attempt completed as a process and its saved conversation is available;
+update only its attempt reference, keeping this review's round, HEAD and counter.
+A killed/lost attempt or an unavailable continuation follows replacement below. Once the
+review record is complete, the next required review is a fresh conversation. Clear an
+unpinned `reviewSession` directly. If it holds retention, release that protection before
+clearing; on failure, save its exact reference and error in `retiredSessions` before clearing
+so settlement can retry while the fresh review proceeds. Never use a reviewer as the
+implementation owner.
+
 If that reviewer cannot continue, state why replacement is necessary, which
 retained evidence the replacement reads, and what it redoes before launching it.
-The replacement reviews every pass with `tier: "full"`. Keep the round number,
+A `retentionReleased` marker on the old reference is not a reason by itself: released
+protection leaves the saved conversation in place, so try it again before replacing it.
+While an old reference is still worth resuming or still needs release, keep it as an entry
+in `retiredSessions` ([task-plan.md](task-plan.md#shape)) rather than dropping it; a later
+release of the new session does not release the old conversation. The replacement reviews every pass with `tier: "full"`. Keep the round number,
 `fixRound`, unit `attempt` and earlier round files; incompleteness neither resets
 history nor counts as progress. Launch the replacement from the same recorded
 reviewer fill, in the same structured launch arguments as [the brief](#brief)
@@ -221,10 +242,10 @@ the PR author; `github-reviews.mjs` reads them and decides what blocks.
 
 - **P0/P1** block (`better-review`'s severity table defines them): fix on the
   unit branch, validate, review again.
-- **P2** never blocks, never reaches a fix worker, and never starts a round.
-  Its dropbox entry is its whole disposition. Route each new entry by the
-  [dropbox questions](dropbox.md#route-every-problem): file it now, drop it,
-  or make it a decision when one says so.
+- **P2** never blocks or starts a blocking-fix round by severity alone. Route each
+  entry by the [dropbox questions](dropbox.md#route-every-problem); explicitly selected
+  [supporting P2 work](dropbox.md#supporting-p2-work) may be fixed in the unit.
+  Keep unrelated P2 in the dropbox; preserve the severity and review verdict.
 - **P3** is skipped: no dropbox entry, no issue, no round. A P3 that still
   reaches the result file (a posted result, an older reviewer) is ignored.
 - Dispose of every P0-P2 finding: `resolved` on the reviewed HEAD, or `deferred`
@@ -232,13 +253,24 @@ the PR author; `github-reviews.mjs` reads them and decides what blocks.
 
 ## Fix loop
 
-Give the fix worker only the `fixBrief`, and act on its `action`:
+Give the [implementation owner](implementation.md#implementation-owner) the `fixBrief`
+and act on its `action`. Keep the generated `reproducers` intact: their source rounds,
+HEADs and original triggers identify earlier witnesses, not passing results on this
+candidate. Read the retained cases and run against the candidate workspace at their
+relative `cwd`; preserve their input/state and expected contract when adapting a checkout
+path. `reproducerGaps` identifies malformed historical metadata without supplying a runnable
+command: inspect the original record, establish a valid candidate-local case, and report any
+remaining gap without rewriting history. Findings without an executable witness retain their
+existing requirement evidence.
+Add only supporting P2
+explicitly selected under [dropbox routing](dropbox.md#supporting-p2-work), with the
+recorded criterion and reason; the generated blocker list remains P0/P1 only.
 
 | `action` | When | Fix worker |
 |---|---|---|
 | `fix` | first blocking round | Make the smallest complete fix for each finding's `rule` and close every applicable row in its `paths`; do not require centralization. |
 | `test-first` | a P0/P1 survived the last fix | On the escalation model, for each `recurring` finding, before changing code: name the broken rule and its concrete open paths, reuse sufficient tests and add focused cases for missing proof, and see the open cases fail. Fix the rule until the applicable cases pass. A table-driven test may cover several paths; no new architecture is required. |
-| `one-by-one` | the last fix introduced new P0/P1 | One fix worker per finding, in turn, each with the smallest change that closes every row of its `paths` at the rule's owner. |
+| `one-by-one` | the last fix introduced new P0/P1 | The implementation owner fixes findings sequentially in its continued session, each with the smallest change that closes every row of its `paths` at the rule's owner. |
 
 **Fix the broken rule on every applicable path, without requiring a refactor.**
 A shared owner is useful when it makes the fix smaller and clearer; it is not a
@@ -251,8 +283,9 @@ different-person sign-in cases without inventing unrelated event combinations.
 Have each fix worker run the checks its change affects and return the
 commands and results; push, and let CI run. Then pick the new HEAD's
 [tier](#tier-then-verdict): a fix is delta or full, never skip, so spawn the
-next round's reviewer with the previous result file and the `fixBrief`. Deferred P2
-return only if now rated P1. Record `reviewedHead` only on a `pass` verdict. A later
+next round's fresh reviewer with the previous result file and the `fixBrief`, naming any
+supporting P2 changed in that patch. Deferred P2 return as findings only if now rated
+P1; evaluate changed supporting work as part of the fix diff. Record `reviewedHead` only on a `pass` verdict. A later
 commit, a CI fix included, needs its own `pass`: a [carry](#carry-after-a-pass) when this round passed.
 
 A `decide` verdict pauses the fix loop on a question: a spec finding came back after a

package/skills/engineering/resolve-issues/references/task-plan.md

@@ -92,6 +92,9 @@ Fleet `status`: `pending`, `in-flight`, `succeeded`, `failed`,
 | `attempt`, `retries`, `escalations` | Attempt number; cycle counts; escalation-model attempts |
 | `worker`, `workerSince`, `clock` | Slot identifier of any worker running for the unit (implementer, reviewer, fix), `null` when none; when that worker started (ISO time, for [stuck-worker checks](expire.md#waits)); attempt and cumulative wall time |
 | `workerKind` | `implement`, `fix`, or `review`, set with `worker`; the [live-capacity scheduler](implementation.md#live-capacity) (`next-actions.mjs`) prints `worker-kind` for any other kind or none. An infrastructure diagnosis or a test-first worker is a `fix` worker. The explorer is the `explore` fleet row's worker, never a unit's; a merge-queue watcher is not a worker |
+| `implementationOwner` | Optional saved implementation conversation: `{runId, sessionId?, cwd?, kind?, retentionReleased?}`. `runId` is its latest attempt; `kind` is `implement` (default) or `fix`, never `review`; `cwd`, when recorded, matches `workspace`. Save spawn/resume receipts here, independently of `worker`; a parked owner occupies no slot. The scheduler emits `owner-resume` for a usable owner or an explicit `ownerUnavailable` reason for replacement; `retentionReleased: true` only records that optional cleanup protection lapsed, so it never makes the owner unusable and the saved conversation stays the resume target while the harness holds it. Old plans remain readable. See [ownership](implementation.md#implementation-owner). |
+| `reviewSession` | Optional `{runId, sessionId?, head, round, retentionReleased?}` for the current unfinished review. Keep it only for same-HEAD/same-scope continuation, and clear it when that round completes so the next completed-review round starts fresh. A `retentionReleased` marker is history, not a reason to replace: try the same round's saved conversation while it exists. It is never an implementation owner or a slot reservation. |
+| `retiredSessions` | Optional references kept beside a replaced implementation owner or unfinished reviewer: `{runId, sessionId?, kind, retentionReleased?, reason?}`. Only for a conversation still worth resuming or still holding protection that must be released later; an ordinary resume or replacement needs no entry here, and a later release of the new session does not release an older conversation. |
 | `estimatedLines` | Preflight assessment estimate |
 | `sizeCheck` | Measures, `verdict` (the size check's per-unit verdict; `stop` means held), scope and proof verdicts, split or verification path; `runWhole: true` once a recommendation to run a held unit whole is accepted |
 | `note` | SHA, expiry reason code, failure and response, or blocker; for active debugging, the immediate acceptance checkpoint, baseline/result link and next distinguishing test ([delivery progress](../SKILL.md#delivery-progress)) |
@@ -142,7 +145,10 @@ what a later launch of the slot repeats; a pair of model ids is not.
 (`open`, `resolved`, `deferred`), `resolvedHead`, `dropboxId` or `followUpUrl`. Copy them
 from `review-verdict.mjs`: on `fix` its `fix` list as `open`; on `pass` its
 `deferred` list as `deferred` and every open P0/P1 as `resolved`. Never defer
-a P0/P1.
+a P0/P1. For selected [supporting P2 work](dropbox.md#supporting-p2-work), record the
+selection in `decisions`; after verification, mark its plan finding `resolved` with
+`resolvedHead` and put the check/result in the unit's existing note/result. Preserve
+the original review and retire its pending dropbox entry as documented there.
 
 `decisions` entry: id, timestamp, the human's words, what it changes,
 `supersedes` when it replaces one, and `answers`: the run-relative file of each
@@ -153,7 +159,16 @@ recommendation's reason; its human's words are the invocation.
 
 ### Worker selection on resume
 
-**A launch repeats the saved fill, never a reconstruction of it.** On Pi the
+Distinguish resuming the workflow from continuing one saved conversation. For an ordinary
+same-conversation `subagent_resume`, pass its attempt ID and new feedback, omitting role,
+model and effort so the harness preserves its recorded recipe. The resume tool's schema
+may differ from spawn: do not replay a role selector it cannot accept. A required changed
+selection can continue only through controls both explicitly authorized and advertised by
+that API; otherwise record why replacement is needed and launch fresh from the required
+fill with its retained evidence. A resolved role default alone never authorizes a model pin.
+Keep the original model/effort as run evidence and preserve all review/progress counters.
+
+**A fresh or replacement launch repeats the saved fill, never a reconstruction of it.** On Pi the
 launch authority stays the live role resolver ([shared-modules.md](shared-modules.md#model-slots)):
 its `launch` is `{ role }` unless an explicit task override or this host's own
 preference asked for a model or effort, and a resolved role default is never

package/skills/engineering/resolve-issues/references/workspaces.md

@@ -17,7 +17,9 @@ checkout) and `targetBranch`. A unit already records `workspace`, `branch` and
                  "baseSha": "<exact SHA>", "identity": "<returned by the helper>" },
   "resources": [ { "role": "review|scratch|tools", "kind": "directory|clone|worktree",
                    "path": "<absolute>", "disposable": true,
-                   "state": "preparing|ready", "identity": "<returned by the helper>" } ],
+                   "state": "preparing|ready", "identity": "<returned by the helper>",
+                   "retention": { "kind": "generated", "format": "generic|pnpm-install|pnpm-store|uv-venv|next-build",
+                                  "recipe": "<retained rebuild command>", "inputs": ["<absolute source input>"] } } ],
   "cleanup": { "state": "pending|applying|complete|retained",
                "headSha": "<the unit's headSha>", "reason": "<retained only>" } }
 ```
@@ -75,11 +77,31 @@ Do not admit another worker while that owner's cleanup is `applying`; the
 3. Persist the returned `nextLifecycle` on the unit **before** spawning the
    worker, and give the worker that workspace path and only the resources it
    needs. Resources are recorded before they are used.
-4. Reuse it. Retries, fix rounds, and every review round run in the same
-   workspace and the same review clone; a later prepare verifies identity,
-   branch, and base instead of recreating. Never reset, replace, or allocate a
-   second tree for one attempt, and plan a private tool cache or scratch copy
-   only when the work needs one.
+4. Each disposable generated resource carries its explicit `retention` intent:
+   kind, supported format, reconstruction recipe and retained source input paths
+   ([retention.md](retention.md#verify-generated-formats-and-rebuild-inputs)).
+   After persisting the ready lifecycle and before worker admission, run:
+
+   ```bash
+   node <skill-base-dir>/scripts/retention.mjs register-owned \
+     --repo <repo-root> --run <run> --unit <unit> \
+     --last-used-at <current-ISO-timestamp> --apply --json
+   ```
+
+   The command considers only declared resources. Record its registered, deferred
+   and uncovered results; report a refusal rather than claiming full daily coverage.
+   An empty typed installation can be deferred while its producing worker installs
+   it. After that worker settles and its handle is cleared, repeat registration
+   for the populated resource. Registration grants no early release of unfinished
+   work. Whole workspaces, credential directories, unique scripts and required
+   evidence stay outside disposable declarations.
+5. Before reusing a registered resource, run the read-only
+   [rebuild status check](retention.md#check-before-reuse). Rebuild a missing or
+   partial installation with the retained repository contract before admitting its
+   dependent worker; directory existence is not readiness. Refresh registration and
+   activity without releasing the owner after reconstruction. Retries, fix rounds
+   and review rounds reuse the same workspace and review clone. A later prepare
+   verifies identity, branch and base; it does not reset or replace them.
 
 `kind`: a linked `worktree` where a plain checkout is enough; an independent
 `clone` when the first Git-mutating worker runs in a sandbox that cannot write a
@@ -126,8 +148,10 @@ It removes nothing else: no ignored-file stripping, no pruning, and no
 answer retains everything, whole. Keep, never clean: a blocked, cancelled,
 pending, or supervised merge-ready unit's environment, whatever its timestamp; a
 tree a worker may still use; a tree whose ownership or delivery cannot be proved.
-No cleanup runs by age, idle time, or a name pattern, and a legacy
-`*-workspaces` directory is never adopted or deleted.
+Whole-workspace cleanup never runs by age, idle time, or a name pattern, and a legacy
+`*-workspaces` directory is never adopted or deleted. Separate [resource retention](retention.md)
+uses explicit registrations and age thresholds for reconstructable children while keeping
+the workspace, Git history and progress records.
 
 ## Evidence and handoff
 
@@ -149,8 +173,14 @@ On startup, before scheduling, read only:
 node <skill-base-dir>/scripts/cleanup-runs.mjs recover --repo <repo-root> --json
 ```
 
-It lists unfinished recorded operations — a `preparing` workspace, an `applying`
-cleanup, a lock, an orphaned worktree — in every run regardless of age. It
+Also inspect resource-retention recovery before admission:
+
+```bash
+node <skill-base-dir>/scripts/retention.mjs recover --repo <repo-root> --json
+```
+
+Workspace recovery lists unfinished recorded operations — a `preparing` workspace,
+an `applying` cleanup, a lock, an orphaned worktree — in every run regardless of age. It
 activates no workflow and cleans nothing by itself: continue the plan, then
 prepare or clean what it names and persist the result.
 

package/skills/engineering/resolve-issues/scripts/daily-cleanup.mjs

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+// Enroll only the explicitly named repository; no project-directory discovery.
+import { createHash } from 'node:crypto'
+import { execFileSync, spawnSync } from 'node:child_process'
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { delimiter, dirname, isAbsolute, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+const SCRIPT = fileURLToPath(import.meta.url)
+const RETENTION = join(dirname(SCRIPT), 'retention.mjs')
+const PATH = '/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin'
+
+function days(value) {
+  const number = Number(value)
+  if (!Number.isSafeInteger(number) || number < 1) throw new Error('--older-than-days must be a positive integer')
+  return number
+}
+
+function escapeXml(value) {
+  return String(value).replace(/[&<>"']/g, char => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;' })[char])
+}
+
+function systemdArgument(value) {
+  if (/[\r\n\0]/.test(value)) throw new Error('Scheduler paths cannot contain line breaks or NUL')
+  return `"${String(value).replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/%/g, '%%').replace(/\$/g, '$$')}"`
+}
+
+// Prefer the PATH alias for this exact runtime. Package managers can remove a
+// versioned Cellar directory while keeping their stable opt/bin alias current.
+export function durableNodePath(executable = process.execPath, searchPath = process.env.PATH ?? '') {
+  let identity
+  try { identity = realpathSync(executable) } catch { return executable }
+  for (const directory of searchPath.split(delimiter)) {
+    if (!isAbsolute(directory)) continue
+    const candidate = join(directory, 'node')
+    try { if (realpathSync(candidate) === identity) return candidate } catch { /* not this runtime */ }
+  }
+  return executable
+}
+
+export function schedulePlan({ repo, olderThanDays = 30, platform = process.platform,
+  home = homedir(), node = durableNodePath(), script = SCRIPT } = {}) {
+  if (!isAbsolute(repo ?? '')) throw new Error('--repo must be an absolute repository path')
+  const canonical = realpathSync(repo)
+  if (!existsSync(join(canonical, '.git'))) throw new Error('Daily cleanup requires a Git repository root')
+  if (!isAbsolute(home) || !isAbsolute(node) || !isAbsolute(script)) throw new Error('Scheduler paths must be absolute')
+  const retention = days(olderThanDays)
+  const id = `io.1above.resolve-issues.cleanup.${createHash('sha256').update(canonical).digest('hex').slice(0, 20)}`
+  const args = [node, script, 'run', '--repo', canonical, '--older-than-days', String(retention), '--apply']
+  if (args.some(value => /[\r\n\0]/.test(value))) throw new Error('Scheduler paths cannot contain line breaks or NUL')
+  if (platform === 'darwin') {
+    const logs = join(home, 'Library', 'Logs', 'resolve-issues')
+    const file = join(home, 'Library', 'LaunchAgents', `${id}.plist`)
+    const content = `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0"><dict>\n<key>Label</key><string>${id}</string>\n<key>ProgramArguments</key><array>${args.map(arg => `<string>${escapeXml(arg)}</string>`).join('')}</array>\n<key>RunAtLoad</key><true/>\n<key>StartInterval</key><integer>43200</integer>\n<key>EnvironmentVariables</key><dict><key>PATH</key><string>${PATH}</string></dict>\n<key>StandardOutPath</key><string>${escapeXml(join(logs, `${id}.log`))}</string>\n<key>StandardErrorPath</key><string>${escapeXml(join(logs, `${id}.err`))}</string>\n</dict></plist>\n`
+    return { repo: canonical, id, retentionDays: retention, platform, files: [{ path: file, content }], directories: [logs], args }
+  }
+  if (platform === 'linux') {
+    const root = join(home, '.config', 'systemd', 'user')
+    const service = `[Unit]\nDescription=Reclaim declared disposable resolve-issues resources for ${id}\n\n[Service]\nType=oneshot\nEnvironment=PATH=${PATH}\nExecStart=${args.map(systemdArgument).join(' ')}\nTimeoutStartSec=30min\n`
+    const timer = `[Unit]\nDescription=Daily tiered resource retention for ${id}\n\n[Timer]\nOnCalendar=daily\nOnBootSec=5min\nPersistent=true\nUnit=${id}.service\n\n[Install]\nWantedBy=timers.target\n`
+    return { repo: canonical, id, retentionDays: retention, platform,
+      files: [{ path: join(root, `${id}.service`), content: service }, { path: join(root, `${id}.timer`), content: timer }], directories: [], args }
+  }
+  throw new Error(`Daily cleanup scheduling is unsupported on ${platform}; no job was installed`)
+}
+
+const defaultRun = (command, args) => execFileSync(command, args, { encoding: 'utf8', timeout: 30000, stdio: ['ignore', 'pipe', 'pipe'] })
+
+export function installSchedule(options = {}, { run = defaultRun, uid = process.getuid?.() } = {}) {
+  const plan = schedulePlan(options)
+  for (const file of plan.files) {
+    let current = file.path
+    while (current !== dirname(current)) {
+      try {
+        if (lstatSync(current).isSymbolicLink()) throw new Error(`Scheduler path is a symbolic link: ${current}`)
+      } catch (error) { if (error.code !== 'ENOENT') throw error }
+      current = dirname(current)
+    }
+  }
+  const domain = `gui/${uid}`
+  const same = plan.files.every(file => existsSync(file.path) && readFileSync(file.path, 'utf8') === file.content)
+  if (same) {
+    try {
+      if (plan.platform === 'darwin') run('launchctl', ['print', `${domain}/${plan.id}`])
+      else {
+        run('systemctl', ['--user', 'is-enabled', `${plan.id}.timer`])
+        run('systemctl', ['--user', 'is-active', `${plan.id}.timer`])
+      }
+      return { ok: true, action: 'unchanged', ...plan }
+    } catch { /* A saved job is not necessarily loaded. */ }
+  }
+  // Preflight the user scheduler before saving any files.
+  if (plan.platform === 'darwin') run('launchctl', ['print', domain])
+  else run('systemctl', ['--user', 'show-environment'])
+  for (const path of plan.directories) mkdirSync(path, { recursive: true })
+  if (plan.platform === 'darwin') {
+    let loaded = false
+    try { run('launchctl', ['print', `${domain}/${plan.id}`]); loaded = true } catch { /* absent */ }
+    if (loaded) run('launchctl', ['bootout', `${domain}/${plan.id}`])
+  }
+  for (const file of plan.files) {
+    mkdirSync(dirname(file.path), { recursive: true })
+    writeFileSync(file.path, file.content, { mode: 0o600 })
+  }
+  if (plan.platform === 'darwin') run('launchctl', ['bootstrap', domain, plan.files[0].path])
+  else {
+    run('systemctl', ['--user', 'daemon-reload'])
+    run('systemctl', ['--user', 'enable', '--now', `${plan.id}.timer`])
+  }
+  return { ok: true, action: 'installed', ...plan }
+}
+
+export function uninstallSchedule(options = {}, { run = defaultRun, uid = process.getuid?.() } = {}) {
+  const plan = schedulePlan(options)
+  if (plan.platform === 'darwin') {
+    let loaded = false
+    try { run('launchctl', ['print', `gui/${uid}/${plan.id}`]); loaded = true } catch { /* absent */ }
+    if (loaded) run('launchctl', ['bootout', `gui/${uid}/${plan.id}`])
+  } else run('systemctl', ['--user', 'disable', '--now', `${plan.id}.timer`])
+  for (const file of plan.files) rmSync(file.path, { force: true })
+  if (plan.platform === 'linux') run('systemctl', ['--user', 'daemon-reload'])
+  return { ok: true, action: 'uninstalled', repo: plan.repo, id: plan.id }
+}
+
+export function runDaily({ repo, olderThanDays = 30, apply = false } = {}, run = spawnSync) {
+  if (!isAbsolute(repo ?? '')) throw new Error('--repo must be absolute')
+  const args = [RETENTION, apply ? 'apply' : 'plan', '--repo', realpathSync(repo), '--generated-days', '7', '--artifact-days', String(days(olderThanDays)), '--json']
+  if (apply) args.push('--apply')
+  const result = run(process.execPath, args, { encoding: 'utf8', timeout: 25 * 60 * 1000, maxBuffer: 4 * 1024 * 1024 })
+  if (result.error) throw result.error
+  return { status: result.status ?? 1, stdout: result.stdout ?? '', stderr: result.stderr ?? '' }
+}
+
+export function main(argv) {
+  try {
+    const [command, ...rest] = argv
+    const options = {}
+    for (let i = 0; i < rest.length; i++) {
+      if (rest[i] === '--apply') { options.apply = true; continue }
+      if (!['--repo', '--older-than-days'].includes(rest[i])) throw new Error(`Unknown argument ${rest[i]}`)
+      const flag = rest[i]
+      const value = rest[++i]
+      if (!value || value.startsWith('--')) throw new Error(`${flag} needs a value`)
+      options[flag === '--repo' ? 'repo' : 'olderThanDays'] = value
+    }
+    if (!options.repo) throw new Error('--repo is required')
+    options.repo = resolve(options.repo)
+    if (command === 'run') {
+      const result = runDaily(options)
+      process.stdout.write(result.stdout)
+      process.stderr.write(result.stderr)
+      return result.status
+    }
+    if (options.apply) throw new Error('--apply is only valid with run')
+    const result = command === 'install' ? installSchedule(options)
+      : command === 'uninstall' ? uninstallSchedule(options)
+        : command === 'plan' ? schedulePlan(options) : null
+    if (!result) throw new Error('Usage: daily-cleanup.mjs install|uninstall|plan|run --repo PATH [--older-than-days 30] [--apply]')
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`)
+    return 0
+  } catch (error) {
+    process.stderr.write(`daily-cleanup: ${error.message}\n`)
+    return 1
+  }
+}
+
+if (isMainModule(import.meta.url)) process.exitCode = main(process.argv.slice(2))

package/skills/engineering/resolve-issues/scripts/dropbox.mjs

@@ -20,7 +20,8 @@
 //   --line, any change to the file counts)? Prints { inDiff, do }: `inDiff` true means fix it in this unit.
 // add: append one entry; the coordinator is the only writer. An implementer entry inside the
 //   unit's diff is refused (`refused` in the output) because the unit caused it. A review entry inside the diff
-//   is kept and marked `inDiff`: the review loop never fixes P2. The same location, kind and
+//   is kept and marked `inDiff`: the coordinator selects supporting work by the delivery
+//   criterion, not location or severity alone. The same location, kind and
 //   summary (or, for a review, the same unit and finding id) is one entry. `--decision` records
 //   a question for the human: never posted, listed in the handback. Prints { id, duplicate, inDiff }.
 // from-review: add every P2 in a review result that has no followUpUrl or dropboxId, and