@1aboveio/skills 1.0.17 → 1.0.19

package/skills/engineering/harness-runtime/agent-catalog.mjs

@@ -36,7 +36,8 @@
 //   PI_AGENT_CATALOG_COMMAND  JSON argv array: '["node","/abs/agent-catalog.mjs"]'
 //                             (preferred when arguments are needed), or a bare
 //                             executable token: 'pi-agent-catalog'.
-//   default                   pi-agent-catalog on PATH.
+//   default                   pi-agent-catalog on PATH, then (Pi only) the
+//                             catalog in Pi's installed npm packages on ENOENT.
 // A bare token cannot carry arguments — that is deliberate, so no quoting rule
 // sneaks shell semantics in. Nothing here runs npm/npx, resolves a sibling
 // checkout, or reads a registry.
@@ -48,8 +49,9 @@
 // install (`~/.agents/skills/{resolve-issues,harness-runtime}`). No path in this
 // file is relative to a source-domain layout.
 import { spawnSync } from 'node:child_process'
-import { readFileSync } from 'node:fs'
-import { resolve as resolvePath } from 'node:path'
+import { readFileSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, resolve as resolvePath } from 'node:path'
 
 export const AGENT_CATALOG_PROTOCOL_VERSION = 1
 export const DEFAULT_AGENT_CATALOG_COMMAND = 'pi-agent-catalog'
@@ -210,6 +212,27 @@ export function resolveCatalogCommand(env = process.env) {
   return parseCommandSpec(spec)
 }
 
+function installedPiCatalogCommand(request, env) {
+  if (request.harness !== 'pi' || env?.[AGENT_CATALOG_COMMAND_ENV]?.trim()) return null
+  const configuredRoot = request.userRoot || env?.PI_CODING_AGENT_DIR || join(homedir(), '.pi', 'agent')
+  const root = configuredRoot === '~' ? homedir()
+    : configuredRoot.startsWith('~/') ? join(homedir(), configuredRoot.slice(2)) : configuredRoot
+  for (const entry of [
+    ['pi-better-harness', 'bin', 'pi-agent-catalog.mjs'],
+    ['pi-better-subagents', 'agent-catalog.mjs'],
+  ]) {
+    const script = resolvePath(root, 'npm', 'node_modules', ...entry)
+    try {
+      if (statSync(script).isFile()) {
+        return { executable: process.execPath, args: [script], source: 'pi-installed' }
+      }
+    } catch (error) {
+      if (error.code !== 'ENOENT' && error.code !== 'ENOTDIR') throw error
+    }
+  }
+  return null
+}
+
 function normalizeAvailable(value, label = 'available') {
   if (value === undefined) return { ok: true, available: [] }
   if (!Array.isArray(value)) {
@@ -864,17 +887,27 @@ export function resolveAgentCatalog({
   }
   const commandResult = resolveCatalogCommand(env)
   if (!commandResult.ok) return commandResult
-  const { command } = commandResult
+  let { command } = commandResult
+  const invoke = () => runner({
+    executable: command.executable,
+    args: command.args,
+    input: `${JSON.stringify(request)}\n`,
+    timeoutMs,
+    env,
+  })
 
   let run
   try {
-    run = runner({
-      executable: command.executable,
-      args: command.args,
-      input: `${JSON.stringify(request)}\n`,
-      timeoutMs,
-      env,
-    })
+    run = invoke()
+    // Only a missing default command permits installed-package lookup. An
+    // explicit choice or a resolver that ran and failed stays authoritative.
+    if (run?.error?.code === 'ENOENT') {
+      const installed = installedPiCatalogCommand(request, env)
+      if (installed) {
+        command = installed
+        run = invoke()
+      }
+    }
   } catch (error) {
     return blocked(
       AGENT_CATALOG_BLOCK_CODES.COMMAND_UNAVAILABLE,

package/skills/engineering/harness-runtime/contracts.md

@@ -14,4 +14,4 @@ When no supported native question tool is advertised, concise free-text input is
 
 Model discovery and catalog persistence remain separate from question planning. Current-turn tool availability is never inferred from model or harness configuration. Source-tree imports outside `skills/engineering` are unsupported until an installation-aware adapter entrypoint exists; consumers must not copy the runtime to work around that boundary.
 
-`agent-catalog.mjs` is the consumer bridge to the harness-owned agent catalog: one versioned JSON request on stdin (`version`, `harness`, `cwd`, `available`, `foregroundModel`, `fallbackToForeground`, `launchCapabilities`, `hostPreferences`, `overrides`, `tiers`, …) and one JSON response on stdout with four worker slots. It resolves the resolver command from `PI_AGENT_CATALOG_COMMAND` (a JSON argv array, or one bare executable token) or defaults to `pi-agent-catalog` on PATH, runs it with no shell, bounds its output and runtime, and validates the response. Those host fields are validated and forwarded unchanged — nothing is inferred or completed here, so an unstated launch control or tier stays unstated. A missing, broken, or declining resolver is a reported block; the bridge never falls back to a skill-owned model ladder and never installs anything. `discover-models.mjs` and `model-catalog.mjs` remain for consumers that still import them and are no longer part of model-slot selection.
+`agent-catalog.mjs` is the consumer bridge to the harness-owned agent catalog: one versioned JSON request on stdin (`version`, `harness`, `cwd`, `available`, `foregroundModel`, `fallbackToForeground`, `launchCapabilities`, `hostPreferences`, `overrides`, `tiers`, …) and one JSON response on stdout with four worker slots. It resolves the resolver command from `PI_AGENT_CATALOG_COMMAND` (a JSON argv array, or one bare executable token) or defaults to `pi-agent-catalog` on PATH. For Pi only, when that default command is missing (`ENOENT`), it checks the installed `pi-better-harness` then standalone `pi-better-subagents` catalog under `<agent-dir>/npm/node_modules` and invokes the first installed entrypoint through the current Node executable. The agent directory is the request's `userRoot`, then `PI_CODING_AGENT_DIR`, then `~/.pi/agent`. Explicit commands and resolvers that execute but fail remain authoritative; there is no project-checkout search or second resolver after a catalog failure. The bridge runs with no shell, bounds its output and runtime, and validates the response. Those host fields are validated and forwarded unchanged — nothing is inferred or completed here, so an unstated launch control or tier stays unstated. A missing, broken, or declining resolver is a reported block; the bridge never falls back to a skill-owned model ladder and never installs anything. `discover-models.mjs` and `model-catalog.mjs` remain for consumers that still import them and are no longer part of model-slot selection.

package/skills/engineering/resolve-issues/SKILL.md

@@ -8,7 +8,7 @@ dependencies:
   - better-review
   - golden-path
   - harness-runtime
-release-version: 0.48.1
+release-version: 0.49.1
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Resolve issues
@@ -83,6 +83,7 @@ Read each procedure right before its stage; never substitute your own.
 | Implementation loop and opening each PR | [references/implementation.md](references/implementation.md) |
 | Read-only warehouse canary | [references/canary.md](references/canary.md) |
 | Owned workspaces: plan, prepare, cleanup, recover, inventory | [references/workspaces.md](references/workspaces.md) |
+| Daily resource retention: enrollment, age tiers, preview, registration, apply | [references/retention.md](references/retention.md) |
 | Independent review | [references/review.md](references/review.md) |
 | Routing small problems; posting them at the end | [references/dropbox.md](references/dropbox.md) |
 | CI, queue, and merge | [references/ci.md](references/ci.md) |
@@ -143,7 +144,8 @@ Treat a missing or unreadable result as incomplete; resume a dead spawn once in
 
 Follow [preflight.md](references/preflight.md):
 
-0. **Ready label:** resume the spec's run if one exists; run `ready-check.mjs`;
+0. **Retention and ready label:** enroll this repository's daily resource cleanup
+   through the persistent installed skill; resume the spec's run if one exists; run `ready-check.mjs`;
    stop on an `unreadable` outcome; ask at step 6 on `unlabeled` or a `missing` compaction
    hook (`install-hooks.mjs --check`; shortcut: warn).
 1. **Model slots:** record the fast-path fills without asking; the models and

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

@@ -3,7 +3,21 @@
 Run these steps in order, in every run, including a one-unit run. Ask nothing
 until step 6.
 
-## 0. Ready label
+## 0. Repository retention and ready label
+
+Enroll this repository's daily tiered retention through the installed skill copy:
+
+```bash
+node <skill-base-dir>/scripts/daily-cleanup.mjs install --repo <canonical-repo-root>
+```
+
+Repeat on each invocation to refresh the same job, never discover sibling projects.
+Use a persistent installed skill path, not a temporary worktree. Report an enrollment
+failure as "daily cleanup not enabled" and continue the issue workflow. The daily
+job cleans only explicitly registered disposable resources; it preserves run history.
+See [retention.md](retention.md) for age tiers, registration and uninstall. Register
+owned reconstructable resources when they are created and update their activity before
+reuse; never turn an inventory guess into deletion authority.
 
 **One run per spec.** Before anything else, find the spec's run:
 
@@ -52,8 +66,8 @@ The script exits 0 whenever it ran (2 if it could not); read `outcome` in its JS
   planned from an issue that cannot be read.
 - **Exit 2** (the script could not run): fix the issue reference and rerun.
 
-Skip this step for a local or pasted spec. Count only GitHub's native
-sub-issues, never a checklist.
+Skip only the ready-label check for a local or pasted spec; repository retention
+enrollment still runs. Count only GitHub's native sub-issues, never a checklist.
 
 ### Compaction hook
 

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/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))