@1aboveio/skills 1.0.18 → 1.0.19

package/skills/engineering/engineering-runtime/coherence/workflow.json

@@ -369,7 +369,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "65d5a8011e64fb3a49cb45bf8fdb066d21138faed67287421bcd17f10b0c7bc0",
+      "contentDigest": "93ac20a3d5d41b233b13e521ba1b65d0a3e339958422a56ffad00a844656a23f",
       "digestExcludes": []
     },
     {
@@ -382,7 +382,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "b554ced1c8af517ed49ad3a0c6c2d2f5b2f74bb6e1313b7e56e00177e30bae7c",
+      "contentDigest": "915715a605bf78f6f69cb8c95f7227548a6d71a6ef0ce502b5b5c5a357676d19",
       "digestExcludes": []
     },
     {
@@ -395,7 +395,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "8e35a14aea5d7e7b4830f7817438ce6a6eb7c5a6e9c31768aa76c4328e181115",
+      "contentDigest": "1ef2fd2ad328c373c7c6fe42007908766860cd8051e1807739797303aaadeae4",
       "digestExcludes": []
     },
     {
@@ -408,7 +408,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "38150518fe71cd567eeee1c76cec15bcd4b0cd5cde9ef6f90748e462807b8b9f",
+      "contentDigest": "3c9509027191a2b2612f3905defb5ed9c47580709ba77b46c0e8433d354c4d33",
       "digestExcludes": []
     },
     {
@@ -421,7 +421,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "a53c1f2212fd38fc464ea2b86ce5ed37f61052fc884a4873308bd158b33ee174",
+      "contentDigest": "5e419edc77397a9021a24fc9da83d07c83aa786853dcb24916d8fb2655f81ea9",
       "digestExcludes": []
     },
     {
@@ -434,7 +434,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "cc5d24bb0952a4c67bed48bc154fd3ef4115bd3162459411b0a71e48251fe342",
+      "contentDigest": "ecee12f24d18d49ec1be030e3f831c3d07a66f37b0b16aa5efef365ca381e558",
       "digestExcludes": []
     },
     {
@@ -447,7 +447,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "3579deef1765207f521b231bd1d21795c791f773f44c634830b0a301c42998f9",
+      "contentDigest": "2fbd1a9e15087045fa80b47d9b6db8695009c900c2e4aeeab71207875b071c74",
       "digestExcludes": []
     },
     {
@@ -460,7 +460,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "be5333b8c2dcd229e7caa395274a5e7695dc301a7ad855122d881d73cb99911d",
+      "contentDigest": "8c33282acdf9a7b3ba3adf46065249126efdd8669487ad7def1b4302155db3dd",
       "digestExcludes": []
     },
     {
@@ -473,7 +473,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "36bd7b643df2a9217b297f5da084cfd9113f0d578a56721cb302b92f8b9f1aad",
+      "contentDigest": "e612b320be1b3aee539a26494e2048e0bbdc1947166fa4cffbdfe8085a64b50a",
       "digestExcludes": []
     },
     {
@@ -486,7 +486,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "6fe762cf05a852f4c52007106e29f606e8c716a29510f7c1d4abc3ec59b96442",
+      "contentDigest": "53732d354995ca40c0325b2f860a4facf2e79b9d6d373fbc76a5ce5b3a1f1e29",
       "digestExcludes": []
     },
     {
@@ -499,7 +499,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "f7286a2fe3a4f1c0d233f25fff89f5a46bb0e932d1b6f07b857b5b3e3a398d54",
+      "contentDigest": "61f8b7f04887b86338984f03527fdaf66ec90df7ff89c19ee9dca6f362fe212a",
       "digestExcludes": []
     },
     {
@@ -512,13 +512,13 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "35d54af1d31fb8e0bd0e80929e807be0f8d4a342882897ba1e9bdc396e4e0db6",
+      "contentDigest": "ad9bdbfbaeb4c575f8fad5b53367403096594aafce8e686926ddb734c185155a",
       "digestExcludes": [
         "coherence/workflow.json"
       ]
     }
   ],
-  "releaseIdentity": "ea12741260694df094ae6fda1597a15df1e8f31a6db2069e38b8bc1cf13083f2",
+  "releaseIdentity": "2ed547516d442d0bfad21952001956420f71a972849049507530f80ad16eda83",
   "lifecycleAuthority": "native-skills-cli",
   "repairRecipe": {
     "id": "engineering-workflow-dependency-first",

package/skills/engineering/ensure-coverage/SKILL.md

@@ -2,7 +2,7 @@
 name: ensure-coverage
 description: "Define or audit behavior-first test criteria — ACs, required test levels, mock/integration/E2E policy — across three axes: breadth (Coverage Ledger), depth (over-mocking), presentation (perceivability of browser surfaces). NOT judging whether a single test is any good (test-quality), authoring browser tests (e2e-test), reviewing a PR (better-review), or delivering issues (resolve-issues)."
 disable-model-invocation: true
-release-version: 0.49.0
+release-version: 0.49.1
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Ensure Coverage

package/skills/engineering/golden-path/SKILL.md

@@ -3,7 +3,7 @@ name: golden-path
 description: "Golden-path E2E: the short list of user journeys whose failure blocks a release, kept in a repo as one contract (golden-paths.json) with a generated GOLDEN_PATHS.md and a generated GitHub Actions workflow, and run against a local build or a deployed URL for an ALIVE/DEAD verdict. Use to set golden paths up in a repo ('init golden paths', 'add golden-path CI'), to migrate an older smoke.manifest.json or a hand-built smoke setup ('audit', 'migrate smoke'), to add, change, or remove a golden path, to ask 'is the build alive?' or run them before a PR or release, or when a change touches a flow listed in GOLDEN_PATHS.md. NOT for writing the Playwright specs themselves (e2e-test), deciding what a change must prove (ensure-coverage), or general workflow YAML (github-actions)."
 dependencies:
   - e2e-test
-release-version: 0.49.0
+release-version: 0.49.1
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Golden path

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

@@ -3,7 +3,7 @@ name: harness-runtime
 description: Internal import-only library shared by first-party engineering packages. Not a workflow skill; never select or invoke it as a user capability.
 disable-model-invocation: true
 user-invocable: false
-release-version: 0.49.0
+release-version: 0.49.1
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Harness Runtime

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

@@ -8,7 +8,7 @@ dependencies:
   - better-review
   - golden-path
   - harness-runtime
-release-version: 0.49.0
+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))