@cratis/pi 7.104.0 → 7.105.1

package/package/corpus/skills/cratis-engineering-local-cross-repo-verification/scripts/cratis-local-packages.sh

@@ -55,7 +55,7 @@ Commands (COMMAND --help shows these instructions too):
     consumer resolves must be STAMP (none resolved: exit 1).
   verify-pack --composition FILE [--json]
   verify-assets CONSUMER-PATH --composition FILE [--json]
-  use-nuget CONSUMER --composition FILE [--pin-transitive]
+  use-nuget CONSUMER --composition FILE [--task ID] [--pin-transitive] [--private-cache]
     Opt-in mixed-version NuGet closure: tab-separated producer NAME STAMP
     ABSOLUTE_WORKTREE rows, then package PRODUCER PACKAGE_ID rows. Case-insensitive
     IDs have one owner. All declared artifacts must exist; nothing is built/repacked.
@@ -66,25 +66,34 @@ Commands (COMMAND --help shows these instructions too):
     The next mutation recovers interrupted work, or refuses and preserves unknown
     ownership/drift. Active compositions retain member artifacts. Restore before
     changing a composition or switching between it and a legacy overlay.
-  pack-nuget PRODUCER STAMP [--property NAME=VALUE]... PROJECT-OR-SLN...
+  list [--json] [--stamp STAMP]
+    Read-only inventory of feed artifacts and stamp records, including legacy stamps.
+    Shows producer, task state, live/total consumers and age. Requires node; npm
+    package names are read from tarballs with tar. Takes no session lock.
+  finish --task ID [--apply]
+    Print records naming ID; --apply marks that task finished. No match is success.
+    Finishing never restores consumers or removes packages. Requires node.
+  pack-nuget PRODUCER STAMP [--task ID] [--property NAME=VALUE]... PROJECT-OR-SLN...
     Release-pack each target into the NuGet feed; requires dotnet. Each --property
     becomes one -p:NAME=VALUE argument of that command only (closure prints the
     properties of each map pack row); no environment variable carries them.
-  pack-npm PRODUCER STAMP
+  pack-npm PRODUCER STAMP [--task ID]
     Requires node, npm and Yarn 4, and a completed repository build. Temporarily
     version non-private workspaces, pack each with npm pack --ignore-scripts (the
     publish workflows' tool, so the tarball matches the published one) as
     <scope>-<name>-<version>.tgz, and restore tracked manifests even on failure.
     This helper does not build or run lifecycle scripts.
-  use-nuget CONSUMER STAMP [--pin-transitive] [PACKAGE-ID...]
+  use-nuget CONSUMER STAMP [--task ID] [--pin-transitive] [--private-cache] [PACKAGE-ID...]
     Create a CPM overlay importing the repository's own Directory.Packages.props.
     Transitive pinning stays as the consumer sets it; --pin-transitive forces it on so
     stamped IDs the consumer does not pin still take effect (can raise NU1109 floors).
     Defaults to every stamped package ID in the feed. Prints properties and sourceable
     env. With source mapping, also prints the required restore --configfile.
+    --private-cache (or CRATIS_LOCAL_PRIVATE_CACHE=1) exports NUGET_PACKAGES in env
+    and registers a marked cache at <absolute-git-dir>/cratis-local-nuget.
     Non-CPM: manually use an untracked project copy with explicit PackageReference
     versions and dotnet restore --source FEED/nuget; do not edit shipped versions.
-  use-npm CONSUMER STAMP [--dir REL]
+  use-npm CONSUMER STAMP [--task ID] [--dir REL]
     --dir REL names a Yarn project in a subdirectory (restore and clean follow it).
     Requires node and tar. Back up package.json, yarn.lock (including existing edits),
     and git diff; add file-tarball resolutions for every stamped feed package.
@@ -93,18 +102,37 @@ Commands (COMMAND --help shows these instructions too):
     Restore npm backups when only overlay resolutions and their local lockfile
     entries changed (including yarn install). Refuse unrelated changes and retain
     backups for review. Remove CPM/env overlays
-    and run check. No git checkout is used on consumer files.
+    and run check. Keep the private NuGet cache. No git checkout is used on consumer files.
   check REPO [--staged]
     Scan added/changed tracked lines (staged-only if requested), plus all contents
     of untracked, non-ignored files. Reports path:line:pattern and file counts.
-  clean [CONSUMER] [--stamp STAMP | --all] [--apply] [--dir REL]
+  clean [CONSUMER] [--stamp STAMP | --all | --expired [--online]] [--apply] [--dir REL] [--private-cache]
     Default: list all local feed/cache/image/session subjects, without deleting.
     --apply deletes listed subjects (docker rmi, never force). Refuses more than
     CRATIS_LOCAL_CLEAN_MAX subjects (default 500), or unresolved npm backups.
     Refuses selected stamps referenced by registered live consumer overlays/manifests;
     restore those consumers first. Dry-run uses the same protection.
     Known sessions are registered in FEED/sessions; an optional consumer also
-    discovers its per-worktree session. Docker probes have a 10-second deadline.
+    discovers its per-worktree session. Registered private caches are also scanned;
+    missing/mismatched markers or unsafe cache paths refuse the entire clean (2).
+    clean CONSUMER --private-cache lists the whole marked cache for removal; --apply
+    removes it and its registration only after restore and with no live stamp.
+    Removes selected FEED/stamps/STAMP records with the artifacts on --apply.
+    --expired keeps unrecorded stamps, compositions and live references; expires
+    finished producing tasks, gone consumers or stamps superseded by a release.
+    Release evidence is offline NuGet caches unless --online opts into 10-second
+    NuGet/npm checks. Kept stamps succeed (0). --apply also prunes gone consumers
+    and missing sessions. Uses the same fuse, lock and dry-run default.
+    Docker probes have a 10-second deadline.
+
+Pack/use commands (including --composition) accept --task ID, overriding
+CRATIS_LOCAL_TASK, else record null. Convention: owner/repo#number. IDs match
+^[A-Za-z0-9][A-Za-z0-9._#:/-]{0,127}$ and are JSON values, never path components.
+Registry mutations require node. Successful packs record producer HEAD and branch;
+use records consumers after publication; restore retains their history.
+Invalid records: pack/use and selected clean subjects refuse with 2. Restore reads only
+session stamps after restoring overlays; finish skips invalid records with WARNINGs.
+Restore/finish exit 1 for invalid records; list shows invalid rows and exits 1.
   --self-test
     Isolated scratch HOME tests; npm uses inherited PATH to discover node.
     Other tests use system PATH. Reports passed and skipped counts.
@@ -114,6 +142,8 @@ if present (trusted shell code), then use these defaults for unset variables:
   CRATIS_LOCAL_FEED=${XDG_CACHE_HOME:-$HOME/.cache}/cratis/local-feed
   CRATIS_LOCAL_SESSION_DIR=<absolute-git-dir>/cratis-local (per checkout)
   NUGET_PACKAGES=$HOME/.nuget/packages
+  CRATIS_LOCAL_PRIVATE_CACHE=0 (1 opts use-nuget into a private worktree cache)
+  CRATIS_LOCAL_TASK=optional task ID (overridden by --task ID)
   CRATIS_LOCAL_CLEAN_MAX=500
   CRATIS_LOCAL_RUN=optional executable wrapper, invoked for each heavy step as:
     "$CRATIS_LOCAL_RUN" build LABEL -- COMMAND ARGUMENTS...
@@ -229,7 +259,7 @@ validate_session() {
         [ -e "$entry" ] || [ -L "$entry" ] || continue
         [ ! -L "$entry" ] || die "symlink in session: $entry"
         case "${entry##*/}" in
-            repo|stamp|env|npm-dir|Directory.Packages.props|cratis-local.targets|nuget.config) [ -f "$entry" ] || die "unexpected session entry: $entry" ;;
+            repo|stamp|env|npm-dir|nuget-cache|Directory.Packages.props|cratis-local.targets|nuget.config) [ -f "$entry" ] || die "unexpected session entry: $entry" ;;
             npm-backup|composition) [ -d "$entry" ] || die "unexpected session entry: $entry" ;;
             *) die "unrecognized file in session (preserved): $entry" ;;
         esac
@@ -246,6 +276,50 @@ register_session() {
         printf '%s\n' "$session" >> "$FEED/sessions"
     fi
 }
+# Validate every helper-owned path component before trusting a cache registration.
+validate_private_cache() {
+    local repo=$1 cache=$2 git_dir parent relative
+    git_dir=$(git -C "$repo" rev-parse --absolute-git-dir) || die "cannot find cache repository: $repo"
+    case "$cache" in "$git_dir/"*) relative=${cache#"$git_dir/"} ;; *) die "private cache outside repository git directory: $cache" ;; esac
+    case "/$relative/" in */../*|*/./*|*//*) die "unsafe private cache path: $cache" ;; esac
+    parent=$cache
+    while [ "$parent" != "$git_dir" ]; do
+        [ -d "$parent" ] && [ ! -L "$parent" ] || die "unsafe private cache directory: $parent"
+        parent=${parent%/*}
+    done
+    [ -f "$cache/.cratis-local-cache" ] && [ ! -L "$cache/.cratis-local-cache" ] || die "private cache marker missing: $cache"
+    [ "$(cat "$cache/.cratis-local-cache")" = "$repo" ] || die "private cache marker mismatch: $cache"
+}
+registered_private_cache() {
+    local session=$1 repo cache
+    validate_session "$session"
+    [ -f "$session/repo" ] || die "private cache session has no repository: $session"
+    repo=$(cat "$session/repo"); cache=$(cat "$session/nuget-cache")
+    [ "$(repo_root "$repo")" = "$repo" ] && [ "$(session_path "$repo")" = "$session" ] || die "private cache session no longer matches repository: $session"
+    validate_private_cache "$repo" "$cache"
+    printf '%s\n' "$cache"
+}
+prepare_private_cache() {
+    local repo=$1 cache=$2 session=$3
+    validate_session "$session"
+    if [ -e "$cache" ] || [ -L "$cache" ]; then validate_private_cache "$repo" "$cache"; fi
+    if [ -f "$session/nuget-cache" ]; then
+        [ "$(registered_private_cache "$session")" = "$cache" ] || die "different private cache already registered: $session"
+    fi
+}
+register_private_cache() {
+    local repo=$1 cache=$2 session=$3
+    prepare_private_cache "$repo" "$cache" "$session"
+    mkdir -p "$cache"
+    printf '%s\n' "$repo" > "$cache/.cratis-local-cache"
+    printf '%s\n' "$cache" > "$session/nuget-cache"
+}
+private_cache_restored() {
+    local session=$1 entry
+    for entry in stamp env Directory.Packages.props cratis-local.targets nuget.config npm-backup composition; do
+        [ ! -e "$session/$entry" ] && [ ! -L "$session/$entry" ] || die "private cache still referenced by $session/$entry; restore first"
+    done
+}
 xml_escape() { printf '%s' "$1" | sed -e 's/\&/\&amp;/g' -e 's/</\&lt;/g' -e 's/>/\&gt;/g' -e 's/"/\&quot;/g' -e "s/'/\&apos;/g"; }
 
 # Next patch of the highest reachable vX.Y.Z tag; sets NEXT_BASE.
@@ -313,9 +387,326 @@ stamp() {
     printf '%s-local.%s.g%.7s\n' "$base" "$(date -u +%Y%m%d%H%M)" "$sha"
 }
 
+# All stamp-record mutations use this path, after builds or overlay publication.
+registry_update() {
+    [ "$DRY" -eq 0 ] || return 0
+    [ -n "$SESSION_LOCK" ] || acquire_session_lock
+    registry "$@"
+}
+registry_consumer() {
+    if ! (registry_update use "$@"); then
+        printf 'WARNING: stamp registry update failed; overlay kept; restore before cleaning\n' >&2
+        exit 1
+    fi
+}
+registry() {
+    need node
+    case "$1" in list|expiry) expiry_context "$@" ;; esac
+    node - "$FEED" "$TASK" "$TMP" "$@" <<'REGISTRY'
+const fs = require('node:fs'), path = require('node:path'), cp = require('node:child_process');
+const [feed, taskValue, scratch, operation, ...args] = process.argv.slice(2);
+const task = taskValue || null, root = path.join(feed, 'stamps');
+const stampPattern = /^([0-9]+\.[0-9]+\.[0-9]+)-(local\.[0-9]{12}|train)\.g[0-9a-f]{7}$/;
+const taskPattern = /^[A-Za-z0-9][A-Za-z0-9._#:/-]{0,127}$/;
+const now = new Date().toISOString();
+function fail(message) { throw new Error(message); }
+function safe(file, directory = false) {
+    const relative = path.relative(feed, file);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) fail('outside stamp registry: ' + file);
+    let current = feed;
+    for (const part of ['', ...relative.split(path.sep).filter(Boolean)]) {
+        current = path.join(current, part);
+        const stat = fs.lstatSync(current, {throwIfNoEntry:false});
+        if (stat && (stat.isSymbolicLink() || (current !== file || directory ? !stat.isDirectory() : !stat.isFile()))) fail('unsafe registry path: ' + current);
+    }
+}
+function recordPath(stamp) {
+    if (!stampPattern.test(stamp)) fail('invalid registry stamp: ' + stamp);
+    const file = path.join(root, stamp, 'record.json'); safe(file); return file;
+}
+function read(stamp) {
+    const file = recordPath(stamp);
+    if (!fs.existsSync(file)) return null;
+    const value = JSON.parse(fs.readFileSync(file, 'utf8'));
+    const match = stamp.match(stampPattern);
+    if (value.schema !== 1 || value.stamp !== stamp || value.base !== match[1] || value.kind !== (match[2] === 'train' ? 'train' : 'local') ||
+        !Array.isArray(value.packs) || !Array.isArray(value.consumers) || !value.tasks || typeof value.tasks !== 'object' || Array.isArray(value.tasks) ||
+        !Number.isFinite(Date.parse(value.created)) || !Number.isFinite(Date.parse(value.updated))) fail('invalid stamp record: ' + file);
+    for (const pack of value.packs) {
+        if (!['nuget','npm'].includes(pack.ecosystem) || !Array.isArray(pack.ids) || pack.ids.some(id => typeof id !== 'string') ||
+            !pack.producer || ['repo','worktree','branch','head'].some(k => typeof pack.producer[k] !== 'string') ||
+            !(pack.task === null || typeof pack.task === 'string' && taskPattern.test(pack.task)) || !Number.isFinite(Date.parse(pack.time))) fail('invalid pack record: ' + file);
+    }
+    for (const consumer of value.consumers) {
+        if (['worktree','session','ecosystem','time'].some(k => typeof consumer[k] !== 'string') || !['nuget','npm'].includes(consumer.ecosystem) ||
+            !(consumer.task === null || typeof consumer.task === 'string' && taskPattern.test(consumer.task)) ||
+            !Number.isFinite(Date.parse(consumer.time)) || consumer.restored && !Number.isFinite(Date.parse(consumer.restored))) fail('invalid consumer record: ' + file);
+    }
+    for (const [id, state] of Object.entries(value.tasks)) {
+        if (!taskPattern.test(id) || !state || !(state.finished === null || typeof state.finished === 'string' && Number.isFinite(Date.parse(state.finished)))) fail('invalid task record: ' + file);
+    }
+    return value;
+}
+function warning(stamp, error) {
+    console.error('WARNING: stamp registry: ' + path.join(root, stamp, 'record.json') + ': ' + error.message);
+    process.exitCode = 1;
+}
+function sessionStamps(session) {
+    const files = ['stamp','Directory.Packages.props','cratis-local.targets','nuget.config','env','npm-backup/expected-package.json','composition/manifest.tsv'];
+    const found = new Set();
+    for (const name of files) {
+        const file = path.join(session, name);
+        if (!fs.existsSync(file)) continue;
+        for (const stamp of fs.readFileSync(file, 'utf8').match(/[0-9]+\.[0-9]+\.[0-9]+-(?:local\.[0-9]{12}|train)\.g[0-9a-f]{7}/g) || []) found.add(stamp);
+    }
+    for (const stamp of found) console.log(stamp);
+}
+function stamps() {
+    safe(root, true);
+    if (!fs.existsSync(root)) return [];
+    return fs.readdirSync(root).filter(s => stampPattern.test(s)).sort();
+}
+function write(value) {
+    const file = recordPath(value.stamp), next = file + '.next'; safe(next);
+    fs.mkdirSync(path.dirname(file), {recursive:true, mode:0o700});
+    value.updated = now;
+    fs.writeFileSync(next, JSON.stringify(value, null, 2) + '\n', {mode:0o600});
+    fs.chmodSync(next, 0o600); fs.renameSync(next, file);
+}
+function consumerState(consumer) {
+    if (consumer.restored) return 'restored';
+    if (!fs.existsSync(consumer.worktree)) return 'gone';
+    const git = cp.spawnSync('git', ['-C', consumer.worktree, 'rev-parse', '--show-toplevel'], {encoding:'utf8'});
+    if (git.status !== 0 || git.stdout.trim() !== consumer.worktree) return 'gone';
+    return ['env','Directory.Packages.props','cratis-local.targets','nuget.config','npm-backup','composition'].some(n => fs.existsSync(path.join(consumer.session,n))) ? 'live' : 'restored';
+}
+function packages() {
+    const found = new Map();
+    for (const ecosystem of ['nuget','npm']) {
+        const directory = path.join(feed,ecosystem); safe(directory,true);
+        if (!fs.existsSync(directory)) continue;
+        for (const name of fs.readdirSync(directory)) {
+            const match = name.match(/^(.*?)[.-]([0-9]+\.[0-9]+\.[0-9]+-(?:local\.[0-9]{12}|train)\.g[0-9a-f]{7})\.(nupkg|tgz)$/);
+            if (!match || (ecosystem === 'nuget' ? match[3] !== 'nupkg' : match[3] !== 'tgz')) continue;
+            const file = path.join(directory,name); safe(file);
+            let id = match[1];
+            if (ecosystem === 'npm') id = JSON.parse(cp.execFileSync('tar',['-xOf',file,'package/package.json'],{encoding:'utf8'})).name;
+            if (typeof id !== 'string' || !id) fail('invalid package ID: ' + file);
+            const entries = found.get(match[2]) || [];
+            entries.push({id,version:match[2],ecosystem,file}); found.set(match[2],entries);
+        }
+    }
+    return found;
+}
+function worktreeGone(consumer) {
+    if (!fs.statSync(consumer.worktree,{throwIfNoEntry:false})?.isDirectory()) return true;
+    const git = cp.spawnSync('git',['-C',consumer.worktree,'rev-parse','--show-toplevel'],{encoding:'utf8'});
+    return git.status !== 0 || git.stdout.trim() !== consumer.worktree;
+}
+function gone(consumer) {
+    return !fs.statSync(consumer.session,{throwIfNoEntry:false})?.isDirectory() || worktreeGone(consumer);
+}
+function expiryInputs() {
+    const selectedIndex = args.indexOf('--stamp'), selected = selectedIndex < 0 ? null : args[selectedIndex + 1];
+    const sessions = path.join(feed,'sessions'); safe(sessions);
+    if (fs.existsSync(sessions)) {
+        for (const session of fs.readFileSync(sessions,'utf8').split('\n').filter(Boolean)) {
+            const repo = path.join(session,'repo');
+            if (fs.existsSync(repo)) console.log(fs.readFileSync(repo,'utf8').trim() + '\t' + session);
+            else console.log('\t' + session);
+        }
+    }
+    for (const stamp of selected ? [selected] : stamps()) {
+        let value;
+        try { value = read(stamp); } catch (error) { if (args[0] === 'list') continue; throw error; }
+        for (const c of value?.consumers || []) console.log(c.worktree + '\t' + c.session);
+    }
+}
+function contextLines(name) { return fs.readFileSync(path.join(scratch,'expiry-' + name),'utf8').split('\n').filter(Boolean); }
+function atLeast(version, base) {
+    if (!/^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/.test(version)) return false;
+    const a = version.split('.').map(BigInt), b = base.split('.').map(BigInt);
+    for (let i = 0; i < 3; i++) if (a[i] !== b[i]) return a[i] > b[i];
+    return true;
+}
+function offlineRelease(value) {
+    for (const pack of value.packs.filter(p => p.ecosystem === 'nuget')) for (const id of pack.ids) {
+        if (!/^[A-Za-z0-9_][A-Za-z0-9_.-]*$/.test(id)) fail('invalid NuGet release ID: ' + id);
+        for (const cache of contextLines('caches')) {
+            const directory = path.join(cache,id.toLowerCase());
+            // A missing cache is no evidence; actual scan/read errors fail closed.
+            if (!fs.statSync(directory,{throwIfNoEntry:false})) continue;
+            for (const version of fs.readdirSync(directory).sort()) {
+                if (atLeast(version,value.base) && fs.statSync(path.join(directory,version)).isDirectory() &&
+                    fs.statSync(path.join(directory,version,'.nupkg.metadata'),{throwIfNoEntry:false})?.isFile()) return 'released:' + id + '@' + version;
+            }
+        }
+    }
+    return null;
+}
+async function onlineRelease(value) {
+    for (const pack of value.packs) for (const id of pack.ids) {
+        // Test-only override: hermetic unreachable-host fixtures, never a feed setting.
+        const override = process.env.CRATIS_LOCAL_RELEASE_URL_BASE;
+        const url = pack.ecosystem === 'nuget' ? (override || 'https://api.nuget.org/v3-flatcontainer') + '/' + encodeURIComponent(id.toLowerCase()) + '/index.json' :
+            (override || 'https://registry.npmjs.org') + '/' + encodeURIComponent(id);
+        try {
+            const response = await fetch(url,{signal:AbortSignal.timeout(10000)});
+            if (!response.ok) continue;
+            const data = await response.json(), versions = pack.ecosystem === 'nuget' ? data.versions : Object.keys(data.versions || {});
+            if (!Array.isArray(versions)) continue;
+            const version = versions.find(v => typeof v === 'string' && atLeast(v,value.base));
+            if (version) return 'released:' + id + '@' + version;
+        } catch { /* Network failures are not release evidence and never fail cleanup. */ }
+    }
+    return null;
+}
+async function expiry(stamp, value, online = false) {
+    const kept = reason => ({expired:false,reasons:[],kept:[reason]});
+    if (!value) return kept('unrecorded; use clean --stamp ' + stamp);
+    if (contextLines('compositions').includes(stamp)) return kept('active composition member');
+    const reference = contextLines('live').find(line => line.split('\t')[0] === stamp);
+    if (reference) return kept('live reference in ' + reference.slice(reference.indexOf('\t') + 1));
+    const tasks = value.packs.map(p => p.task).filter(t => t !== null);
+    let reason = tasks.length && tasks.every(t => value.tasks[t]?.finished) ? 'task-finished' : null;
+    if (!reason && value.consumers.length && value.consumers.every(gone)) reason = 'consumers-gone';
+    if (!reason) reason = offlineRelease(value);
+    if (!reason && online) reason = await onlineRelease(value);
+    return reason ? {expired:true,reasons:[reason],kept:[]} : kept('active');
+}
+async function expired() {
+    const names = [...new Set([...packages().keys(),...stamps()])].sort();
+    // Validate every subject before reporting decisions or allowing any deletion.
+    const records = names.map(stamp => [stamp,read(stamp)]);
+    for (const [stamp,value] of records) {
+        const decision = await expiry(stamp,value,args.includes('--online'));
+        console.log([decision.expired ? 'expired' : 'kept',stamp,(decision.expired ? decision.reasons : decision.kept).join('; ')].join('\t'));
+    }
+}
+function prune() {
+    const values = stamps().map(read), sessions = path.join(feed,'sessions'); safe(sessions);
+    const before = fs.existsSync(sessions) ? fs.readFileSync(sessions,'utf8') : null;
+    for (const value of values.filter(Boolean)) {
+        // Keep a consumer while its worktree exists: its manifests are still scanned for live references.
+        const consumers = value.consumers.filter(c => !worktreeGone(c));
+        if (consumers.length !== value.consumers.length) { value.consumers = consumers; write(value); }
+    }
+    if (before !== null) {
+        const after = before.split('\n').filter(s => s && fs.statSync(s,{throwIfNoEntry:false})?.isDirectory()).join('\n');
+        const next = sessions + '.next'; safe(next);
+        fs.writeFileSync(next,after ? after + '\n' : '',{mode:0o600}); fs.renameSync(next,sessions);
+    }
+}
+async function list() {
+    const json = args.includes('--json'), index = args.indexOf('--stamp');
+    const selected = index < 0 ? null : args[index + 1];
+    const remaining = args.filter((_,i) => i !== index && i !== index + 1 || index < 0);
+    if (remaining.some(a => a !== '--json') || index >= 0 && !stampPattern.test(selected || '')) fail('list accepts --json and --stamp STAMP');
+    const artifacts = packages(), names = [...new Set([...artifacts.keys(), ...stamps()])].sort();
+    const rows = [];
+    for (const stamp of names.filter(s => !selected || s === selected)) {
+        let value = null, error;
+        try { value = read(stamp); } catch (failure) { error = failure.message; warning(stamp, failure); }
+        const match = stamp.match(stampPattern), created = value?.created || null;
+        rows.push({stamp,base:match[1],kind:match[2] === 'train' ? 'train' : 'local',recorded:error ? 'invalid' : !!value,...(error ? {error} : {}),packages:artifacts.get(stamp) || [],
+            producers:value?.packs.map(p => p.producer) || [],tasks:Object.entries(value?.tasks || {}).map(([id,s]) => ({id,finished:s.finished})),
+            consumers:value?.consumers.map(c => ({worktree:c.worktree,task:c.task,state:consumerState(c)})) || [],created,
+            ageSeconds:created ? Math.max(0,Math.floor((Date.now()-Date.parse(created))/1000)) : null,
+            expiry:error ? {expired:false,reasons:[],kept:['invalid record']} : await expiry(stamp,value)});
+    }
+    if (json) console.log(JSON.stringify({schema:1,feed,stamps:rows}));
+    else {
+        console.log('STAMP\tECOSYS\tPACKAGES(n)\tOWNER(repo@branch)\tTASK(state)\tCONSUMERS(live/total)\tAGE\tRECORDED');
+        for (const r of rows) console.log([r.stamp,[...new Set(r.packages.map(p => p.ecosystem))].join(',') || '-',r.packages.length,
+            r.producers.map(p => p.repo+'@'+p.branch).join(',') || '-',r.tasks.map(t => t.id+'('+ (t.finished ? 'finished' : 'active') +')').join(',') || '-',
+            r.consumers.filter(c => c.state === 'live').length+'/'+r.consumers.length,r.ageSeconds === null ? '-' : r.ageSeconds+'s',r.recorded].join('\t'));
+    }
+}
+function update() {
+    const [stamp, ecosystem, repo, session, cache, ...ids] = args;
+    let value = read(stamp);
+    if (!value) {
+        const match = stamp.match(stampPattern);
+        value = {schema:1,stamp,base:match[1],kind:match[2] === 'train' ? 'train' : 'local',created:now,updated:now,packs:[],consumers:[],tasks:{}};
+    }
+    if (task && !Object.hasOwn(value.tasks,task)) Object.defineProperty(value.tasks,task,{value:{finished:null},enumerable:true,writable:true,configurable:true});
+    if (operation === 'pack') {
+        const git = (...argv) => cp.execFileSync('git',['-C',repo,...argv],{encoding:'utf8'}).trim();
+        const producer = {repo:path.basename(repo),worktree:repo,branch:git('branch','--show-current'),head:git('rev-parse','HEAD')};
+        const entry = {ecosystem,ids,producer,task,time:now};
+        const index = value.packs.findIndex(p => p.ecosystem === ecosystem && p.producer.worktree === repo && p.task === task);
+        if (index < 0) value.packs.push(entry); else value.packs[index] = {...entry,ids:[...new Set([...value.packs[index].ids,...ids])]};
+    } else {
+        const entry = {worktree:repo,session,task,ecosystem,time:now,...(cache ? {cache} : {})};
+        const index = value.consumers.findIndex(c => c.worktree === repo && c.session === session && c.ecosystem === ecosystem && c.task === task);
+        if (index < 0) value.consumers.push(entry); else value.consumers[index] = entry;
+    }
+    write(value);
+}
+async function main() {
+    if (operation === 'list') await list();
+    else if (operation === 'expiry-inputs') expiryInputs();
+    else if (operation === 'expiry') await expired();
+    else if (operation === 'prune') prune();
+    else if (operation === 'pack' || operation === 'use') update();
+    else if (operation === 'restore-stamps') sessionStamps(args[0]);
+    else if (operation === 'remove') {
+        const file = recordPath(args[0]); read(args[0]);
+        if (fs.readdirSync(path.dirname(file)).some(n => n !== 'record.json')) fail('unexpected stamp directory entry');
+        fs.unlinkSync(file); fs.rmdirSync(path.dirname(file));
+    } else {
+        const selected = operation === 'restore' ? [...new Set(args.slice(1))] :
+            operation === 'clean' && args[0] && args[0] !== 'all' ? [args[0]] : stamps();
+        let count = 0;
+        for (const stamp of selected) {
+            let value;
+            try { value = read(stamp); } catch (error) {
+                if (operation !== 'finish' && operation !== 'restore') throw error;
+                warning(stamp, error); continue;
+            }
+            if (!value) continue;
+            if (operation === 'finish' && Object.hasOwn(value.tasks,task)) {
+                console.log((args.includes('--apply') ? 'finish: ' : 'would finish: ') + stamp + ' ' + task); count++;
+                if (args.includes('--apply')) { value.tasks[task].finished = now; write(value); }
+            } else if (operation === 'restore' && value.consumers.some(c => c.session === args[0] && !c.restored)) {
+                for (const c of value.consumers) if (c.session === args[0] && !c.restored) c.restored = now;
+                write(value);
+            } else if (operation === 'clean' && (!args[0] || args[0] === 'all' || stamp === args[0])) {
+                const directory = path.dirname(recordPath(stamp));
+                if (fs.readdirSync(directory).some(n => n !== 'record.json')) fail('unexpected stamp directory entry: ' + directory);
+                console.log(directory);
+            }
+        }
+        if (operation === 'finish' && !count) console.log('no records name task ' + task);
+    }
+}
+main().catch(error => { console.error('ERROR: stamp registry: ' + error.message); process.exitCode = 2; });
+REGISTRY
+}
+
+# Compare file identities/times so a multi-producer stamp does not attribute earlier
+# producers' packages to the current pack. Repacking the same ID is still recorded.
+nuget_pack_files() {
+    node - "$FEED/nuget" "$@" <<'NODE'
+const fs = require('node:fs'), path = require('node:path');
+const [directory, stamp, before] = process.argv.slice(2);
+const files = {};
+for (const name of fs.existsSync(directory) ? fs.readdirSync(directory) : []) {
+    if (!name.endsWith('.' + stamp + '.nupkg')) continue;
+    const file = path.join(directory,name), st = fs.statSync(file, {bigint:true});
+    files[file] = [st.ino,st.size,st.mtimeNs,st.ctimeNs].map(String).join(':');
+}
+if (!before) console.log(JSON.stringify(files));
+else {
+    const previous = JSON.parse(fs.readFileSync(before,'utf8'));
+    for (const [file,identity] of Object.entries(files)) if (previous[file] !== identity) process.stdout.write(file + '\0');
+}
+NODE
+}
+
 pack_nuget() {
     [ $# -ge 3 ] || die 'pack-nuget requires producer, stamp and targets'
-    local repo version target path count=0 property
+    local repo version target path count=0 property ids=()
     local properties=()
     repo=$(repo_root "$1"); version=$2; shift 2
     valid_stamp "$version"; need dotnet
@@ -328,16 +719,23 @@ pack_nuget() {
         properties+=("-p:$property")
     done
     [ $# -ge 1 ] || die 'pack-nuget requires at least one target after the properties'
+    if [ "$DRY" -eq 0 ]; then
+        need node; scratch
+        nuget_pack_files "$version" > "$TMP/pack-before"
+    fi
     mutate mkdir -p "$FEED/nuget"
     for target in "$@"; do
         (cd "$repo" && heavy build "pack NuGet $target" dotnet pack "$target" -c Release "-p:PackageVersion=$version" "-p:Version=$version" ${properties[@]+"${properties[@]}"} -o "$FEED/nuget")
     done
     [ "$DRY" -eq 0 ] || return 0
+    nuget_pack_files "$version" "$TMP/pack-before" > "$TMP/pack-produced"
     while IFS= read -r -d '' path; do
         printf '%s\n' "$path"; count=$((count + 1))
-    done < <(find "$FEED/nuget" -type f -name "*.$version.nupkg" -print0)
+        target=${path##*/}; ids+=("${target%."$version".nupkg}")
+    done < "$TMP/pack-produced"
     [ "$count" -gt 0 ] || failed 'pack produced no matching nupkgs'
     printf 'produced %s nupkgs\n' "$count"
+    registry_update pack "$version" nuget "$repo" '' '' "${ids[@]}"
 }
 
 # Pack one workspace with npm pack (what publish does) into the feed as <scope>-<name>-<version>.tgz.
@@ -358,7 +756,7 @@ pack_npm_workspace() {
 
 pack_npm() {
     [ $# -eq 2 ] || die 'pack-npm requires producer and stamp'
-    local repo version path count=0
+    local repo version path count=0 ids=()
     repo=$(repo_root "$1"); version=$2
     valid_stamp "$version"; need node; need npm; need yarn; scratch
     git -C "$repo" diff --name-only HEAD -- 'package.json' '*/package.json' > "$TMP/modified"
@@ -409,6 +807,10 @@ NODE
     done < <(find "$FEED/npm" -type f -name "*-$version.tgz" -print0)
     [ "$count" -gt 0 ] || failed 'pack produced no matching npm tarballs'
     printf 'produced %s npm tarballs\n' "$count"
+    while IFS= read -r -d '' path; do
+        ids+=("$(node -p 'require(process.argv[1]).name' "$repo/$path")")
+    done < "$TMP/manifests"
+    registry_update pack "$version" npm "$repo" '' '' "${ids[@]}"
 }
 
 source_mapping() {
@@ -478,10 +880,35 @@ nuget_env() {
     printf 'if [ "%s" != %q ]; then\n' "\${$targets_key:-}" "$session/cratis-local.targets"
     printf '  export _CratisLocalPreviousAfterMicrosoftCommonTargets="%s"\nfi\n' "\${$targets_key:-}"
     printf 'export %s=%q\n' "$targets_key" "$session/cratis-local.targets"
+    if [ -n "${PRIVATE_NUGET_CACHE:-}" ]; then printf 'export NUGET_PACKAGES=%q\n' "$PRIVATE_NUGET_CACHE"; fi
 }
 
 use_nuget() {
-    if [ "${2:-}" = --composition ]; then composition use-nuget "$@"; return; fi
+    local private=${CRATIS_LOCAL_PRIVATE_CACHE:-0} PRIVATE_NUGET_CACHE='' option filtered=() private_repo private_session
+    for option in "$@"; do
+        if [ "$option" = --private-cache ]; then private=1; else filtered+=("$option"); fi
+    done
+    set -- ${filtered[@]+"${filtered[@]}"}
+    if [ "$private" = 1 ]; then
+        [ $# -ge 2 ] || die 'use-nuget requires consumer and stamp or composition'
+        private_repo=$(repo_root "$1"); private_session=$(session_path "$private_repo")
+        PRIVATE_NUGET_CACHE=$(git -C "$private_repo" rev-parse --absolute-git-dir)/cratis-local-nuget
+        prepare_private_cache "$private_repo" "$PRIVATE_NUGET_CACHE" "$private_session"
+    fi
+    if [ "${2:-}" = --composition ]; then
+        composition use-nuget "$@"
+        if [ "$private" = 1 ] && [ "$DRY" -eq 0 ]; then register_private_cache "$private_repo" "$PRIVATE_NUGET_CACHE" "$private_session"; fi
+        if [ "$DRY" -eq 0 ]; then
+            local composition_repo composition_session composition_stamp
+            composition_repo=$(repo_root "$1"); composition_session=$(session_path "$composition_repo")
+            scratch
+            cut -f3 "$composition_session/composition/manifest.tsv" | sort -u > "$TMP/registry-stamps"
+            while IFS= read -r composition_stamp; do
+                registry_consumer "$composition_stamp" nuget "$composition_repo" "$composition_session" "$PRIVATE_NUGET_CACHE"
+            done < "$TMP/registry-stamps"
+        fi
+        return
+    fi
     case " $* " in *' --composition '*) die 'cannot mix a stamp or IDs with --composition' ;; esac
     [ $# -ge 2 ] || die 'use-nuget requires consumer and stamp'
     [ ! -d "$(session_path "$(repo_root "$1")")/composition" ] || die 'active composition; restore first'
@@ -527,6 +954,7 @@ use_nuget() {
         return 0
     fi
     register_session "$repo" "$session" "$version"
+    if [ "$private" = 1 ]; then register_private_cache "$repo" "$PRIVATE_NUGET_CACHE" "$session"; fi
     {
         nuget_props_start "$pin"
         for id in "${ids[@]}"; do
@@ -558,8 +986,11 @@ use_nuget() {
     elif [ -f "$session/nuget.config" ]; then
         rm -- "$session/nuget.config"
     fi
+    registry_consumer "$version" nuget "$repo" "$session" "$PRIVATE_NUGET_CACHE"
     printf 'overrode %s NuGet package IDs\n' "${#ids[@]}"
-    printf 'Optional per-worktree cache (set before restore and clean): export NUGET_PACKAGES=%q\n' "$(git -C "$repo" rev-parse --absolute-git-dir)/cratis-local-nuget"
+    if [ "$private" != 1 ]; then
+        printf 'Optional per-worktree cache (set before restore and clean): export NUGET_PACKAGES=%q\n' "$(git -C "$repo" rev-parse --absolute-git-dir)/cratis-local-nuget"
+    fi
 }
 
 # A shared lock covers legacy mutations too: registration rollback must never replace
@@ -952,7 +1383,7 @@ function activate(packages,pin) {
     const props = path.join(repo,'Directory.Packages.props'); plain(props);
     if (exists(session)) {
         plain(session,true);
-        const allowed = new Set(['repo','composition']);
+        const allowed = new Set(['repo','composition','nuget-cache']);
         if (fs.readdirSync(session).some(n => !allowed.has(n))) fail('conflicting active overlay/session; restore first');
         if (exists(path.join(session,'repo')) && fs.readFileSync(path.join(session,'repo'),'utf8') !== repo + '\n') fail('session belongs to another checkout');
     }
@@ -1083,14 +1514,15 @@ function cleanGuard() {
         if (!exists(composition)) continue;
         plain(composition,true); plain(path.join(composition,'manifest.tsv'));
         const versions = fs.readFileSync(path.join(composition,'manifest.tsv'),'utf8').trim().split('\n').map(row => row.split('\t')[2]);
-        if (!selected || selected === 'all' || versions.includes(selected)) fail('active composition retains member artifacts; restore first: ' + known);
+        if (mode === 'clean-members') { for (const version of versions) console.log(version); }
+        else if (!selected || selected === 'all' || versions.includes(selected)) fail('active composition retains member artifacts; restore first: ' + known);
     }
 }
 try {
     safeParents(feed);
     if (mode === 'recover') recover();
     else if (mode === 'restore-state') restoreState();
-    else if (mode === 'clean-guard') cleanGuard();
+    else if (mode === 'clean-guard' || mode === 'clean-members') cleanGuard();
     else {
         const args = [...argv]; if (mode !== 'verify-pack') args.shift();
         if (args.shift() !== '--composition' || !args.length) fail('expected --composition FILE');
@@ -1629,17 +2061,30 @@ NODE
     git -C "$dir" diff HEAD -- package.json yarn.lock > "$backup/before.diff"
     cp "$TMP/package.json" "$backup/expected-package.json"
     cp "$TMP/package.json" "$dir/package.json"
+    registry_consumer "$version" npm "$repo" "$session" ''
     printf 'Next: cd %q && yarn install\n' "$dir"
     printf 'Vite: clear stale prebundles with rm -rf node_modules/.vite\n'
 }
 
 restore() {
     [ $# -eq 1 ] || die 'restore requires a consumer'
-    local repo session backup dir
+    local repo session backup dir stamp
+    local restore_stamps=()
     repo=$(repo_root "$1"); session=$(session_path "$repo"); backup=$session/npm-backup
     validate_session "$session"
+    scratch
+    # Restoring the overlay never depends on node; only the registry bookkeeping does.
+    local registry_node=0
+    if [ "$DRY" -eq 0 ] && command -v node > /dev/null 2>&1; then
+        registry_node=1
+        registry restore-stamps "$session" > "$TMP/restore-stamps"
+        while IFS= read -r stamp; do restore_stamps+=("$stamp"); done < "$TMP/restore-stamps"
+    elif [ "$DRY" -eq 0 ]; then
+        printf 'WARNING: node not found; restoring without updating the stamp registry\n' >&2
+    fi
     if [ -d "$session/composition" ]; then
         composition restore-state "$repo"
+        if [ "$registry_node" -eq 1 ]; then registry_update restore "$session" ${restore_stamps[@]+"${restore_stamps[@]}"}; fi
         if [ "$DRY" -eq 0 ]; then check "$repo"; fi
         return
     fi
@@ -1659,6 +2104,7 @@ restore() {
         mutate rm -rf -- "$backup"
     fi
     mutate rm -f -- "$session/Directory.Packages.props" "$session/cratis-local.targets" "$session/nuget.config" "$session/env" "$session/stamp" "$session/npm-dir"
+    if [ "$registry_node" -eq 1 ]; then registry_update restore "$session" ${restore_stamps[@]+"${restore_stamps[@]}"}; fi
     if [ "$DRY" -eq 0 ]; then check "$repo"; fi
 }
 
@@ -1738,20 +2184,11 @@ bounded_docker() {
 local_artifact() {
     [[ "$1" =~ -(local\.[0-9]{12}|train)\.g[0-9a-f]{7}($|[^0-9A-Za-z]) ]]
 }
-# Legacy registrations name consumers, not an artifact ownership graph. Fail closed
-# for the whole requested cleanup if any selected stamp is still live. Also keep a
-# selected session when its overlays/manifests reference another stamp.
-clean_live_references() {
-    local selected=$1 session repo file found stamp status blocked=0 session_selected
-    while IFS= read -r session; do
-        [ -d "$session" ] && [ -f "$session/repo" ] || continue
-        validate_session "$session"
-        repo=$(cat "$session/repo")
-        [ -d "$repo" ] || continue
-        [ "$(repo_root "$repo")" = "$repo" ] || die "registered consumer no longer matches repository: $repo"
-        session_selected=0
-        if [ -f "$session/stamp" ] && [ "$(cat "$session/stamp")" = "$selected" ]; then session_selected=1; fi
-        # Follow manifest symlinks too; traversal/read failures refuse cleanup.
+# Print stamp<TAB>file. Follow manifest symlinks; traversal/read errors refuse cleanup.
+live_stamps() {
+    local repo session file found stamp status
+    for repo in "$@"; do
+        session=${LIVE_SESSION:-$(session_path "$repo")}
         find -L "$repo" \( -name .git -o -name node_modules \) -prune -o \( -iname nuget.config -o -iname Directory.Packages.props -o -name packages.lock.json -o -name package.json -o -name yarn.lock \) \( -type f -o -type l \) -print0 > "$TMP/live-files" || die "cannot inspect registered consumer: $repo"
         for file in "$session/Directory.Packages.props" "$session/cratis-local.targets" "$session/nuget.config"; do
             if [ -e "$file" ]; then printf '%s\0' "$file" >> "$TMP/live-files"; fi
@@ -1764,35 +2201,96 @@ clean_live_references() {
             [ -n "$found" ] || continue
             while IFS= read -r stamp; do
                 stamp=$(printf '%s' "$stamp" | tr '[:upper:]' '[:lower:]')
-                if [ -z "$selected" ] || [ "$selected" = all ] || [ "$session_selected" -eq 1 ] || [ "$stamp" = "$selected" ]; then
-                    printf 'kept stamp %s: registered live reference in %s\n' "$stamp" "$file"
-                    blocked=1
-                fi
+                printf '%s\t%s\n' "$stamp" "$file"
             done <<< "$found"
         done < "$TMP/live-files"
+    done
+}
+# Legacy clean still refuses the whole request, with its original messages.
+clean_live_references() {
+    local selected=$1 session repo file stamp blocked=0 session_selected
+    while IFS= read -r session; do
+        [ -d "$session" ] && [ -f "$session/repo" ] || continue
+        validate_session "$session"
+        repo=$(cat "$session/repo")
+        [ -d "$repo" ] || continue
+        [ "$(repo_root "$repo")" = "$repo" ] || die "registered consumer no longer matches repository: $repo"
+        session_selected=0
+        if [ -f "$session/stamp" ] && [ "$(cat "$session/stamp")" = "$selected" ]; then session_selected=1; fi
+        LIVE_SESSION=$session live_stamps "$repo" > "$TMP/legacy-live"
+        while IFS=$'\t' read -r stamp file; do
+            if [ -z "$selected" ] || [ "$selected" = all ] || [ "$session_selected" -eq 1 ] || [ "$stamp" = "$selected" ]; then
+                printf 'kept stamp %s: registered live reference in %s\n' "$stamp" "$file"
+                blocked=1
+            fi
+        done < "$TMP/legacy-live"
     done < "$TMP/unique-sessions"
     [ "$blocked" -eq 0 ] || die 'live references retained; restore registered consumers before cleaning (no subjects removed)'
 }
+# The registry supplies recorded consumers as well as registered sessions. Both list
+# and expired clean use exactly this offline context and the same decision function.
+expiry_context() {
+    local repo session cache actual
+    scratch
+    registry expiry-inputs "$@" > "$TMP/expiry-inputs"
+    if [ -n "${EXPIRY_CONSUMER:-}" ]; then printf '%s\t%s\n' "$EXPIRY_CONSUMER" "$(session_path "$EXPIRY_CONSUMER")" >> "$TMP/expiry-inputs"; fi
+    : > "$TMP/expiry-live"; : > "$TMP/expiry-compositions"
+    printf '%s\n' "$NUGET_CACHE" "$HOME/.nuget/packages" > "$TMP/expiry-caches"
+    while IFS= read -r actual; do
+        session=${actual#*$'\t'}; repo=${actual%%$'\t'*}
+        validate_session "$session"
+        if [ -e "$session/nuget-cache" ] || [ -L "$session/nuget-cache" ]; then
+            cache=$(registered_private_cache "$session")
+            printf '%s\n' "$cache" >> "$TMP/expiry-caches"
+        fi
+        if [ -e "$session/composition" ] || [ -L "$session/composition" ]; then
+            composition clean-members all "$session" >> "$TMP/expiry-compositions"
+        fi
+        [ -n "$repo" ] && [ -d "$repo" ] || continue
+        actual=$(git -C "$repo" rev-parse --show-toplevel 2>/dev/null) || continue
+        [ "$actual" = "$repo" ] || continue
+        LIVE_SESSION=$session live_stamps "$repo" >> "$TMP/expiry-live"
+    done < "$TMP/expiry-inputs"
+}
+expired_guard() {
+    local stamp=$1 found file
+    expiry_context expiry
+    if grep -Fxq -- "$stamp" "$TMP/expiry-compositions"; then die "expired stamp changed: active composition member: $stamp"; fi
+    while IFS=$'\t' read -r found file; do
+        [ "$found" != "$stamp" ] || die "expired stamp changed: live reference in $file"
+    done < "$TMP/expiry-live"
+}
+subject_stamp() {
+    local name=${1##*/}
+    if [[ "$name" =~ ([0-9]+\.[0-9]+\.[0-9]+-(local\.[0-9]{12}|train)\.g[0-9a-f]{7}) ]]; then printf '%s\n' "${BASH_REMATCH[1]}"; fi
+}
 clean() {
-    local version='' apply=0 consumer='' arg path cache image session maximum count=0 rel=''
-    local subjects=() kinds=()
+    local version='' apply=0 consumer='' arg path cache image session maximum count=0 rel='' private=0 whole_cache='' whole_session=''
+    local expired=0 online=0 selected_stamp decision reason EXPIRY_CONSUMER=''
+    local subjects=() kinds=() caches=("$NUGET_CACHE") cache_sessions=() filtered_subjects=() filtered_kinds=()
     while [ $# -gt 0 ]; do
         arg=$1; shift
         case "$arg" in
             --stamp) [ $# -gt 0 ] || die '--stamp requires a stamp'; [ -z "$version" ] || die 'choose --stamp or --all'; version=$1; shift; valid_stamp "$version" ;;
             --all) [ -z "$version" ] || die 'choose --stamp or --all'; version=all ;;
+            --expired) expired=1 ;;
+            --online) online=1 ;;
             --apply) apply=1 ;;
+            --private-cache) private=1 ;;
             --dir) [ $# -gt 0 ] || die '--dir requires a relative directory'; rel=${1%/}; shift ;;
             -*) die "unknown clean option: $arg" ;;
             *) [ -z "$consumer" ] || die 'clean takes at most one consumer'; consumer=$(repo_root "$arg") ;;
         esac
     done
+    [ "$expired" -eq 0 ] || [ -z "$version" ] || die '--expired cannot be combined with --stamp or --all'
+    [ "$online" -eq 0 ] || [ "$expired" -eq 1 ] || die '--online requires --expired'
+    [ "$expired" -eq 0 ] || [ "$private" -eq 0 ] || die '--expired cannot remove a whole private cache'
     local registered
-    if [ -n "$consumer" ]; then
+    if [ "$expired" -eq 0 ] && [ -n "$consumer" ]; then
         session=$(session_path "$consumer")
         if [ -e "$session/composition" ] || [ -L "$session/composition" ]; then composition clean-guard "${version:-all}" "$session"; fi
     fi
-    if [ -f "$FEED/sessions" ]; then
+    if [ "$expired" -eq 0 ] && [ -f "$FEED/sessions" ]; then
         while IFS= read -r registered; do
             if [ -e "$registered/composition" ] || [ -L "$registered/composition" ]; then
                 composition clean-guard "${version:-all}"
@@ -1805,6 +2303,37 @@ clean() {
     [ ${#maximum} -le 6 ] || die 'CRATIS_LOCAL_CLEAN_MAX is too large'
     maximum=$((10#$maximum))
     scratch
+    if [ -f "$FEED/sessions" ]; then cat "$FEED/sessions" > "$TMP/sessions"; else : > "$TMP/sessions"; fi
+    if [ -n "$consumer" ]; then session_path "$consumer" >> "$TMP/sessions"; fi
+    sort -u "$TMP/sessions" > "$TMP/unique-sessions"
+    if [ "$expired" -eq 1 ]; then
+        EXPIRY_CONSUMER=$consumer
+        if [ "$online" -eq 1 ]; then registry expiry --online > "$TMP/expiry-decisions"; else registry expiry > "$TMP/expiry-decisions"; fi
+        : > "$TMP/expired-stamps"
+        while IFS=$'\t' read -r decision selected_stamp reason; do
+            printf '%s %s: %s\n' "$decision" "$selected_stamp" "$reason"
+            if [ "$decision" = expired ]; then printf '%s\n' "$selected_stamp" >> "$TMP/expired-stamps"; fi
+        done < "$TMP/expiry-decisions"
+        while IFS= read -r path; do printf '%s\n' "${path#*$'\t'}" >> "$TMP/sessions"; done < "$TMP/expiry-inputs"
+        sort -u "$TMP/sessions" > "$TMP/unique-sessions"
+        caches+=("$HOME/.nuget/packages")
+    fi
+    while IFS= read -r session; do
+        if [ -e "$session/nuget-cache" ] || [ -L "$session/nuget-cache" ]; then
+            cache=$(registered_private_cache "$session")
+            cache_sessions+=("$session"); caches+=("$cache")
+        fi
+    done < "$TMP/unique-sessions"
+    if [ "$private" -eq 1 ]; then
+        [ -n "$consumer" ] || die 'clean --private-cache requires a consumer'
+        whole_session=$(session_path "$consumer")
+        [ -f "$whole_session/nuget-cache" ] || die "no registered private cache: $consumer"
+        whole_cache=$(registered_private_cache "$whole_session")
+        private_cache_restored "$whole_session"
+        clean_live_references ''
+        subjects+=("$whole_cache"); kinds+=(private-cache)
+    fi
+    printf '%s\n' "${caches[@]}" | sort -u > "$TMP/nuget-caches"
     for cache in "$FEED/nuget" "$FEED/npm"; do
         [ -d "$cache" ] || continue
         while IFS= read -r -d '' path; do
@@ -1813,8 +2342,10 @@ clean() {
             subjects+=("$path"); kinds+=(file)
         done < <(find "$cache" -type f \( -name '*.nupkg' -o -name '*.snupkg' -o -name '*.tgz' \) -print0)
     done
-    if [ -d "$NUGET_CACHE" ]; then
-        for cache in "$NUGET_CACHE"/*; do
+    while IFS= read -r path; do
+        [ "$path" != "$whole_cache" ] || continue
+        [ -d "$path" ] || continue
+        for cache in "$path"/*; do
             [ -d "$cache" ] && [ ! -L "$cache" ] || continue
             for path in "$cache"/*-local.* "$cache"/*-train.*; do
                 [ -d "$path" ] && [ ! -L "$path" ] || continue
@@ -1823,7 +2354,7 @@ clean() {
                 subjects+=("$path"); kinds+=(directory)
             done
         done
-    fi
+    done < "$TMP/nuget-caches"
     if [ -n "$consumer" ] && [ ! -f "$consumer${rel:+/$rel}/package.json" ]; then
         printf 'SKIP: no package.json in %s; pass --dir REL for a Yarn project in a subdirectory\n' "$consumer${rel:+/$rel}" >&2
     elif command -v yarn >/dev/null 2>&1 && [ -n "$consumer" ]; then
@@ -1849,12 +2380,10 @@ clean() {
             printf 'SKIP: Docker unavailable or did not respond within 10 seconds\n' >&2
         fi
     else printf 'SKIP: docker is not on PATH\n' >&2; fi
-    if [ -f "$FEED/sessions" ]; then cat "$FEED/sessions" > "$TMP/sessions"; else : > "$TMP/sessions"; fi
-    if [ -n "$consumer" ]; then session_path "$consumer" >> "$TMP/sessions"; fi
-    sort -u "$TMP/sessions" > "$TMP/unique-sessions"
     while IFS= read -r session; do
         [ -d "$session" ] && [ -f "$session/repo" ] && [ -f "$session/stamp" ] || continue
         local_artifact "$(cat "$session/stamp")" || continue
+        if [ "$expired" -eq 1 ] && ! grep -Fxq -- "$(cat "$session/stamp")" "$TMP/expired-stamps"; then continue; fi
         if [ -n "$version" ] && [ "$version" != all ] && [ "$(cat "$session/stamp")" != "$version" ]; then continue; fi
         [ ! -L "$session" ] && [ "$session" != / ] || die "unsafe session: $session"
         validate_session "$session"
@@ -1863,25 +2392,55 @@ clean() {
         [ ! -d "$session/npm-backup" ] || die "unresolved npm backup: $session; restore before cleaning"
         subjects+=("$session"); kinds+=(session)
     done < "$TMP/unique-sessions"
-    clean_live_references "$version"
+    # Stamp records exist only after a registry-aware pack or use; without any, clean needs no node.
+    : > "$TMP/stamp-records"
+    if [ -e "$FEED/stamps" ] || [ -L "$FEED/stamps" ]; then registry clean "$version" > "$TMP/stamp-records"; fi
+    while IFS= read -r path; do subjects+=("$path"); kinds+=(stamp-record); done < "$TMP/stamp-records"
+    if [ "$expired" -eq 1 ]; then
+        for ((arg=0; arg<${#subjects[@]}; arg++)); do
+            if [ "${kinds[$arg]}" = session ]; then selected_stamp=$(cat "${subjects[$arg]}/stamp"); else selected_stamp=$(subject_stamp "${subjects[$arg]}"); fi
+            if grep -Fxq -- "$selected_stamp" "$TMP/expired-stamps"; then
+                filtered_subjects+=("${subjects[$arg]}"); filtered_kinds+=("${kinds[$arg]}")
+            fi
+        done
+        subjects=(${filtered_subjects[@]+"${filtered_subjects[@]}"}); kinds=(${filtered_kinds[@]+"${filtered_kinds[@]}"})
+    else clean_live_references "$version"; fi
     count=${#subjects[@]}
     [ "$count" -le "$maximum" ] || die "clean fuse: $count subjects exceeds $maximum"
     for ((arg=0; arg<count; arg++)); do printf '%s: %s\n' "${kinds[$arg]}" "${subjects[$arg]}"; done
     if [ "$apply" -eq 1 ] && [ "$DRY" -eq 0 ]; then
         for ((arg=0; arg<count; arg++)); do
-            clean_live_references "$version"
+            if [ "$expired" -eq 1 ]; then
+                if [ "${kinds[$arg]}" = session ]; then selected_stamp=$(cat "${subjects[$arg]}/stamp"); else selected_stamp=$(subject_stamp "${subjects[$arg]}"); fi
+                expired_guard "$selected_stamp"
+            else clean_live_references "$version"; fi
+            for session in ${cache_sessions[@]+"${cache_sessions[@]}"}; do registered_private_cache "$session" > /dev/null; done
             path=${subjects[$arg]}
             case "${kinds[$arg]}" in
+                private-cache)
+                    [ "$(registered_private_cache "$whole_session")" = "$path" ] || die "private cache changed: $path"
+                    private_cache_restored "$whole_session"
+                    clean_live_references ''
+                    rm -rf -- "$path"
+                    rm -- "$whole_session/nuget-cache"
+                    # Later subjects still validate all remaining registrations.
+                    cache_sessions=()
+                    while IFS= read -r session; do
+                        if [ -f "$session/nuget-cache" ]; then cache_sessions+=("$session"); fi
+                    done < "$TMP/unique-sessions"
+                    ;;
+                stamp-record) registry_update remove "${path##*/}" ;;
                 image) docker rmi "$path" ;;
                 file) [ -f "$path" ] && [ ! -L "$path" ] || die "clean subject changed: $path"; rm -- "$path" ;;
                 directory) [ -d "$path" ] && [ ! -L "$path" ] || die "clean subject changed: $path"; rm -rf -- "$path" ;;
                 session)
                     [ -f "$path/stamp" ] && [ ! -L "$path" ] && [ ! -e "$path/npm-backup" ] || die "session changed: $path"
                     validate_session "$path"
-                    rm -f -- "$path/repo" "$path/stamp" "$path/env" "$path/npm-dir" "$path/Directory.Packages.props" "$path/cratis-local.targets" "$path/nuget.config"
-                    rmdir -- "$path" ;;
+                    rm -f -- "$path/stamp" "$path/env" "$path/npm-dir" "$path/Directory.Packages.props" "$path/cratis-local.targets" "$path/nuget.config"
+                    if [ ! -f "$path/nuget-cache" ]; then rm -f -- "$path/repo"; rmdir -- "$path"; fi ;;
             esac
         done
+        if [ "$expired" -eq 1 ]; then registry_update prune; fi
         printf 'removed %s subjects\n' "$count"
     else printf 'dry-run: %s subjects (use --apply to remove)\n' "$count"; fi
 }
@@ -1907,15 +2466,18 @@ self_test_nuget_overlay() {
 
 self_test() {
     [ $# -eq 0 ] || die '--self-test takes no arguments'
-    local root home repo feed version output status passed=0 skipped=0 test_key arg map
+    local root home repo feed version output status passed=0 skipped=0 test_key arg map system_path
     # Fixtures use the physical path (macOS TMPDIR is /var -> /private/var) because the helper
     # reports repositories by their git toplevel; symlinked feeds have their own test below.
     scratch; root=$(cd -P "$TMP" && pwd -P)/self-test; mkdir -p "$root/home" "$root/repo"
     map=$root/map.tsv; home=$root/home; repo=$root/repo; feed=$home/.cache/cratis/local-feed
-    # System-only tests stay hermetic; npm tests inherit PATH to discover node.
-    # Both isolate HOME/config and omit the host adapter.
-    st() { env -i HOME="$home" PATH=/usr/bin:/bin:/usr/sbin:/sbin TMPDIR="$TMP" /bin/bash "$SELF" "$@"; }
-    stm() { env -i HOME="$home" PATH=/usr/bin:/bin:/usr/sbin:/sbin TMPDIR="$TMP" CRATIS_LOCAL_MAP="$map" /bin/bash "$SELF" "$@"; }
+    # Isolate tool discovery, adding only node for the stamp registry. npm tests
+    # inherit PATH. Both isolate HOME/config and omit the host adapter.
+    need node; mkdir -p "$root/registry-bin"
+    ln -s "$(command -v node)" "$root/registry-bin/node"
+    system_path=$root/registry-bin:/usr/bin:/bin:/usr/sbin:/sbin
+    st() { env -i HOME="$home" PATH="$system_path" TMPDIR="$TMP" /bin/bash "$SELF" "$@"; }
+    stm() { env -i HOME="$home" PATH="$system_path" TMPDIR="$TMP" CRATIS_LOCAL_MAP="$map" /bin/bash "$SELF" "$@"; }
     has() { grep -Fq -- "$1" "$2"; }
     st_npm() { env -i HOME="$home" PATH="$PATH" TMPDIR="$TMP" /bin/bash "$SELF" "$@"; }
     git -C "$repo" init -q
@@ -1991,6 +2553,14 @@ LOCK
     passed=$((passed + 5))
     st check "$repo" > "$root/output" || failed 'self-test: clean repo'
     passed=$((passed + 1))
+    # Legacy clean of a feed without stamp records must not need node.
+    mkdir -p "$root/no-registry-feed/nuget"
+    if PATH=/usr/bin:/bin:/usr/sbin:/sbin command -v node > /dev/null 2>&1; then
+        printf 'SKIP: clean without node needs a system PATH without node\n' >&2; skipped=$((skipped + 1))
+    else
+        expect_status 0 'legacy clean without node or stamp records' env -i HOME="$home" PATH=/usr/bin:/bin:/usr/sbin:/sbin TMPDIR="$TMP" CRATIS_LOCAL_FEED="$root/no-registry-feed" /bin/bash "$SELF" clean
+        passed=$((passed + 1))
+    fi
     for test_key in stamp npm props sources targets previous override feed; do
         case "$test_key" in
             stamp) printf '%s\n' "$version" > "$repo/probe" ;;
@@ -2197,6 +2767,8 @@ NODE
         passed=$((passed + 6))
     else printf 'SKIP: use-npm --dir needs node\n'; skipped=$((skipped + 6)); fi
     self_test_live_clean
+    self_test_private_cache
+    self_test_registry
     mkdir -p "$home/.nuget/packages/cratis.test/$version" "$home/.nuget/packages/cratis.test/1.2.3"
     mkdir -p "$home/.nuget/packages/cratis.test/1.2.3-local.keep"
     for arg in nuget npm; do
@@ -2219,10 +2791,351 @@ NODE
     [ -d "$home/.nuget/packages/cratis.test/1.2.3" ] || failed 'self-test: clean removed real version'
     passed=$((passed + 5))
     printf 'SKIP: real dotnet/Yarn/Docker packing is not a hermetic self-test\n'; skipped=$((skipped + 3))
+    self_test_expired
     self_test_matrix
     printf 'self-test: %s passed, %s skipped\n' "$passed" "$skipped"
 }
 
+self_test_expired() {
+    local fixture ef er es ec record result expected stamp=9.8.7-train.gabcdef0
+    local fixtures=('task finished' 'consumers gone' 'released offline cache' 'live reference kept' 'composition kept' 'unrecorded kept' 'dry-run no mutation' 'with stamp' 'fuse' 'online unreachable kept' 'prunes sessions' 'list json expiry' 'invalid record' 'record consumer reference kept' 'private release cache' 'prerelease cache kept' 'older release kept' 'without task kept' 'with all')
+    ext() { env -i HOME="$ef/home" PATH="$system_path" TMPDIR="$TMP" CRATIS_LOCAL_FEED="$ef/feed" NUGET_PACKAGES="$ec" CRATIS_LOCAL_CLEAN_MAX="${limit:-500}" CRATIS_LOCAL_RELEASE_URL_BASE=http://127.0.0.1:1 /bin/bash "$SELF" "$@"; }
+    for fixture in "${fixtures[@]}"; do
+        ef=$root/expired-${fixture// /-}; er=$ef/repo; ec=$ef/cache
+        mkdir -p "$er" "$ef/feed/nuget" "$ec/cratis.expiry/$stamp" "$ef/home"
+        git -C "$er" init -q
+        es=$(git -C "$er" rev-parse --absolute-git-dir)/cratis-local
+        record=$ef/feed/stamps/$stamp/record.json
+        mkdir -p "${record%/*}"
+        printf 'fixture\n' > "$ef/feed/nuget/Cratis.Expiry.$stamp.nupkg"
+        node - "$record" "$stamp" "$er" "$es" "$fixture" <<'NODE'
+const fs = require('node:fs'); const [file,stamp,repo,session,fixture] = process.argv.slice(2), now = new Date().toISOString();
+const finished = ['task finished','live reference kept','composition kept','dry-run no mutation','fuse','prunes sessions','list json expiry','record consumer reference kept'].includes(fixture);
+const r = {schema:1,stamp,base:'9.8.7',kind:'train',created:now,updated:now,
+    packs:[{ecosystem:'nuget',ids:['Cratis.Expiry'],producer:{repo:'Fixture',worktree:repo,branch:'main',head:'a'.repeat(40)},task:'Fixture#1',time:now}],
+    consumers:[],tasks:{'Fixture#1':{finished:finished ? now : null}}};
+if (fixture === 'consumers gone') r.consumers.push({worktree:repo + '/gone',session:session + '-gone',ecosystem:'nuget',task:null,time:now});
+if (fixture === 'record consumer reference kept') r.consumers.push({worktree:repo,session,ecosystem:'nuget',task:null,time:now});
+if (fixture === 'without task kept') r.packs[0].task = null;
+fs.writeFileSync(file,JSON.stringify(r) + '\n');
+NODE
+        expected=0; result=removed
+        case "$fixture" in
+            'released offline cache') mkdir -p "$ec/cratis.expiry/9.8.8"; : > "$ec/cratis.expiry/9.8.8/.nupkg.metadata" ;;
+            'private release cache')
+                mkdir -p "$es" "$er/.git/cratis-local-nuget/cratis.expiry/9.8.7"
+                printf '%s\n' "$er" > "$es/repo"
+                printf '%s\n' "$es" > "$ef/feed/sessions"
+                printf '%s\n' "$er/.git/cratis-local-nuget" > "$es/nuget-cache"
+                printf '%s\n' "$er" > "$er/.git/cratis-local-nuget/.cratis-local-cache"
+                : > "$er/.git/cratis-local-nuget/cratis.expiry/9.8.7/.nupkg.metadata" ;;
+            'live reference kept'|'record consumer reference kept')
+                mkdir -p "$es"; printf '%s\n' "$er" > "$es/repo"
+                if [ "$fixture" = 'live reference kept' ]; then printf '%s\n' "$es" > "$ef/feed/sessions"; fi
+                printf '{"dependencies":{"fixture":"%s"}}\n' "$stamp" > "$er/package.json"
+                result=kept ;;
+            'composition kept')
+                mkdir -p "$es/composition"; printf '%s\n' "$er" > "$es/repo"
+                printf '%s\n' "$es" > "$ef/feed/sessions"
+                printf 'Fixture\tCratis.Expiry\t%s\t%s\n' "$stamp" "$er" > "$es/composition/manifest.tsv"
+                result=kept ;;
+            'unrecorded kept') rm -- "$record"; rmdir "${record%/*}"; result=kept ;;
+            'dry-run no mutation') cp "$record" "$ef/before"; result=kept ;;
+            'with stamp'|'with all'|'fuse'|'invalid record')
+                expected=2; result=kept
+                if [ "$fixture" = 'invalid record' ]; then printf '{broken\n' > "$record"; fi ;;
+            'prerelease cache kept') mkdir -p "$ec/cratis.expiry/9.8.9-preview"; : > "$ec/cratis.expiry/9.8.9-preview/.nupkg.metadata"; result=kept ;;
+            'older release kept') mkdir -p "$ec/cratis.expiry/9.8.6"; : > "$ec/cratis.expiry/9.8.6/.nupkg.metadata"; result=kept ;;
+            'online unreachable kept'|'without task kept') result=kept ;;
+            'list json expiry') result=kept ;;
+            'prunes sessions')
+                mkdir -p "$es"; printf '%s\n' "$er" > "$es/repo"; : > "$es/env"
+                printf '%s\n%s\n' "$ef/missing-session" "$es" > "$ef/feed/sessions"
+                node - "$record" "$es" <<'NODE'
+const fs = require('node:fs'); const [file,session] = process.argv.slice(2), r = JSON.parse(fs.readFileSync(file));
+r.stamp = '9.8.7-train.g1234567'; r.packs[0].task = null;
+r.consumers = [{worktree:r.packs[0].producer.worktree,session,ecosystem:'nuget',task:null,time:r.created},
+    {worktree:'/nonexistent/cratis-expiry-fixture',session:session + '-gone',ecosystem:'nuget',task:null,time:r.created},
+    {worktree:r.packs[0].producer.worktree,session:session + '-missing',ecosystem:'nuget',task:null,time:r.created}];
+const target = file.replace('gabcdef0','g1234567'); fs.mkdirSync(require('node:path').dirname(target)); fs.writeFileSync(target,JSON.stringify(r));
+NODE
+                ;;
+        esac
+        case "$fixture" in
+            'with stamp') expect_status "$expected" 'expired with stamp' ext clean --expired --stamp "$stamp" --apply ;;
+            'with all') expect_status "$expected" 'expired with all' ext clean --all --expired --apply ;;
+            'fuse') limit=0 expect_status "$expected" 'expired fuse' ext clean --expired --apply ;;
+            'online unreachable kept') expect_status 0 'expired online unreachable kept' ext clean --expired --online --apply ;;
+            'dry-run no mutation') expect_status 0 'expired dry-run no mutation' ext clean --expired ;;
+            'list json expiry')
+                expect_status 0 'list json expiry' ext list --json
+                node - "$root/output" <<'NODE' || failed 'list json expiry decision'
+const r = JSON.parse(require('node:fs').readFileSync(process.argv[2])).stamps;
+if (r.length !== 1 || !r[0].expiry.expired || r[0].expiry.reasons.join() !== 'task-finished' || r[0].expiry.kept.length) process.exit(1);
+NODE
+                ;;
+            *) expect_status "$expected" "expired $fixture" ext clean --expired --apply ;;
+        esac
+        if [ "$result" = removed ]; then
+            [ ! -e "$record" ] && [ ! -e "$ef/feed/nuget/Cratis.Expiry.$stamp.nupkg" ] && [ ! -e "$ec/cratis.expiry/$stamp" ] || failed "expired $fixture left subjects"
+        else
+            [ -f "$ef/feed/nuget/Cratis.Expiry.$stamp.nupkg" ] && [ -d "$ec/cratis.expiry/$stamp" ] || failed "expired $fixture removed subjects"
+        fi
+        case "$fixture" in
+            'task finished'|'consumers gone') grep -Fq "expired $stamp: ${fixture// /-}" "$root/output" || failed "expired $fixture reason" ;;
+            'released offline cache') grep -Fq 'released:Cratis.Expiry@9.8.8' "$root/output" || failed 'offline release reason' ;;
+            'live reference kept'|'record consumer reference kept') grep -Fq "kept $stamp: live reference in $er/package.json" "$root/output" || failed 'live override reason' ;;
+            'composition kept') grep -Fq "kept $stamp: active composition member" "$root/output" || failed 'composition override reason' ;;
+            'unrecorded kept') grep -Fq "unrecorded; use clean --stamp $stamp" "$root/output" || failed 'unrecorded reason' ;;
+            'online unreachable kept') grep -Fq "kept $stamp: active" "$root/output" || failed 'network failure removed active stamp' ;;
+            'dry-run no mutation') cmp -s "$record" "$ef/before" || failed 'expired dry-run rewrote record' ;;
+            'prunes sessions')
+                [ "$(cat "$ef/feed/sessions")" = "$es" ] || failed 'expired prunes sessions'
+                node - "$ef/feed/stamps/9.8.7-train.g1234567/record.json" <<'NODE' || failed 'expired prunes consumers'
+// The consumer with a missing session but an existing worktree stays, so its manifests remain protected.
+const r = JSON.parse(require('node:fs').readFileSync(process.argv[2])); if (r.consumers.length !== 2 || r.consumers.some(c => c.worktree.endsWith('fixture')) || !r.consumers.some(c => c.session.endsWith('-missing'))) process.exit(1);
+NODE
+                ;;
+        esac
+    done
+}
+
+self_test_registry() {
+    local rr=$root/'registry repo' rf=$root/registry-feed rb=$root/registry-tools rs record
+    local rt=Cratis/Fixture#1 legacy=1.2.5-train.gabcdef0
+    mkdir -p "$rr" "$rf/nuget" "$rb"
+    git -C "$rr" init -q
+    cp "$repo/Directory.Packages.props" "$rr/Directory.Packages.props"
+    printf '{"name":"@cratis/registry","version":"1.0.0"}\n' > "$rr/package.json"
+    git -C "$rr" add .
+    git -C "$rr" -c user.email=test@example.invalid -c user.name='Registry fixture' commit -qm initial
+    rs=$(git -C "$rr" rev-parse --absolute-git-dir)/cratis-local
+    record=$rf/stamps/$version/record.json
+    # Pack-tool doubles exercise successful/failed pack boundaries without building.
+    cat > "$rb/dotnet" <<'SH'
+#!/bin/bash
+set -eu
+[ ! -e "$CRATIS_LOCAL_FEED/fail-pack" ] || exit 1
+version=''; output=''
+for arg in "$@"; do
+    case "$arg" in -p:PackageVersion=*) version=${arg#*=} ;; esac
+    if [ "$output" = next ]; then output=$arg; fi
+    if [ "$arg" = -o ]; then output=next; fi
+done
+printf 'packed\n' > "$output/Cratis.Registry.$version.nupkg"
+SH
+    printf '#!/bin/sh\nprintf '\''{"location":"."}\\n'\''\n' > "$rb/yarn"
+    cat > "$rb/npm" <<'SH'
+#!/bin/bash
+set -eu
+version=$(node -p 'require("./package.json").version')
+mkdir -p "$TMPDIR/registry-tar/package"
+cp package.json "$TMPDIR/registry-tar/package/package.json"
+tar -czf "$CRATIS_LOCAL_FEED/npm/cratis-registry-$version.tgz" -C "$TMPDIR/registry-tar" package
+SH
+    chmod +x "$rb/dotnet" "$rb/npm" "$rb/yarn"
+    rgt() { env -i HOME="$home" PATH="$rb:$system_path" TMPDIR="$TMP" CRATIS_LOCAL_FEED="$rf" NUGET_PACKAGES="$root/registry-cache" CRATIS_LOCAL_TASK="$rt" /bin/bash "$SELF" "$@"; }
+    rg_assert() { node - "$record" "$@" <<'NODE'
+const fs = require('node:fs'); const [file,kind,version,repo,session] = process.argv.slice(2);
+const r = JSON.parse(fs.readFileSync(file,'utf8'));
+if (r.schema !== 1 || r.stamp !== version || !r.created.endsWith('Z') || !r.updated.endsWith('Z')) process.exit(1);
+if (kind === 'pack' && (r.packs.length !== 2 || !r.packs.some(p => p.ecosystem === 'nuget' && p.ids.join() === 'Cratis.Registry') || !r.packs.some(p => p.ids.includes('@cratis/registry')) || r.packs.some(p => p.producer.worktree !== repo || !/^[0-9a-f]{40}$/.test(p.producer.head)) || (fs.statSync(file).mode & 0o777) !== 0o600)) process.exit(1);
+if (kind === 'use' && (r.consumers.length !== 2 || r.consumers.some(c => c.worktree !== repo || c.session !== session || c.task !== 'Cratis/Fixture#2'))) process.exit(1);
+if (kind === 'restored' && r.consumers.some(c => !c.restored?.endsWith('Z'))) process.exit(1);
+if (kind === 'finished' && !r.tasks['Cratis/Fixture#1'].finished?.endsWith('Z')) process.exit(1);
+NODE
+    }
+    : > "$rf/nuget/Cratis.Previous.$version.nupkg"
+    rgt pack-nuget "$rr" "$version" Fixture.csproj > "$root/output"
+    rgt pack-npm "$rr" "$version" > "$root/output"
+    expect_status 0 'registry pack records' rg_assert pack "$version" "$rr" "$rs"
+    rgt use-nuget "$rr" "$version" --task Cratis/Fixture#2 > "$root/output"
+    rgt use-npm "$rr" "$version" --task Cratis/Fixture#2 > "$root/output"
+    expect_status 0 'registry use consumer' rg_assert use "$version" "$rr" "$rs"
+    expect_status 0 'registry restore consumer' rgt restore "$rr"
+    rg_assert restored "$version" "$rr" "$rs" || failed 'registry restore history'
+    cp "$record" "$root/registry-before"
+    expect_status 0 'registry dry-run no write' rgt --dry-run pack-nuget "$rr" "$legacy" Fixture.csproj
+    [ ! -e "$rf/stamps/$legacy" ] || failed 'registry dry-run created record'
+    rgt --dry-run use-nuget "$rr" "$version" > "$root/output"
+    cmp -s "$record" "$root/registry-before" || failed 'registry dry-run use rewrote record'
+    expect_status 0 'finish task dry-run' rgt finish --task "$rt"
+    cmp -s "$record" "$root/registry-before" || failed 'finish dry-run rewrote record'
+    expect_status 0 'finish task apply' rgt finish --task "$rt" --apply
+    rg_assert finished "$version" "$rr" "$rs" || failed 'finish did not mark task'
+    expect_status 0 'finish unknown task' rgt finish --task Cratis/Unknown#2 --apply
+    grep -Fq 'no records name task' "$root/output" || failed 'finish unknown task message'
+    : > "$rf/nuget/Cratis.Legacy.$legacy.nupkg"
+    expect_status 0 'list unrecorded legacy' rgt list --stamp "$legacy" --json
+    node -e 'const r=JSON.parse(require("fs").readFileSync(process.argv[1])).stamps;if(r.length!==1||r[0].recorded||r[0].packages[0].id!=="Cratis.Legacy")process.exit(1)' "$root/output" || failed 'list legacy missing'
+    rgt list --json > "$root/registry-list"
+    rg_json() { node - "$root/registry-list" "$rf" <<'NODE'
+const fs = require('node:fs'); const [file,feed] = process.argv.slice(2), data = JSON.parse(fs.readFileSync(file));
+if (data.schema !== 1 || data.feed !== feed || data.stamps.length !== 2) process.exit(1);
+const keys = ['stamp','base','kind','recorded','packages','producers','tasks','consumers','created','ageSeconds','expiry'].sort().join();
+for (const r of data.stamps) {
+    if (Object.keys(r).sort().join() !== keys || typeof r.expiry.expired !== 'boolean' || !Array.isArray(r.expiry.reasons) || !Array.isArray(r.expiry.kept)) process.exit(1);
+    for (const p of r.packages) if (Object.keys(p).sort().join() !== 'ecosystem,file,id,version') process.exit(1);
+    for (const c of r.consumers) if (c.state !== 'restored') process.exit(1);
+}
+NODE
+    }
+    expect_status 0 'list json schema' rg_json
+    cp "$record" "$root/registry-good"
+    printf '{"schema":2}\n' > "$record"
+    cp "$record" "$root/registry-bad"
+    expect_status 2 'registry rejects bad schema' rgt clean --stamp "$version" --apply
+    cmp -s "$record" "$root/registry-bad" || failed 'registry rewrote bad schema'
+    printf '{broken\n' > "$record"
+    expect_status 2 'registry rejects malformed JSON' rgt clean --stamp "$version" --apply
+    cp "$root/registry-good" "$record"
+    mv "$rf/stamps" "$rf/real-stamps"; ln -s "$rf/real-stamps" "$rf/stamps"
+    expect_status 2 'registry symlink refused' rgt finish --task "$rt" --apply
+    rm "$rf/stamps"; mv "$rf/real-stamps" "$rf/stamps"
+    ln -s "$root/registry-good" "$record.next"
+    expect_status 2 'registry next symlink refused' rgt finish --task "$rt" --apply
+    rm "$record.next"
+    expect_status 2 'registry bad task id' rgt pack-nuget "$rr" "$version" --task 'bad task' Fixture.csproj
+    : > "$rf/fail-pack"
+    expect_status 1 'registry failed pack no write' rgt pack-nuget "$rr" "$legacy" Fixture.csproj
+    [ ! -e "$rf/stamps/$legacy" ] || failed 'failed pack wrote record'
+    rm "$rf/fail-pack"
+    # Post-publication failures preserve overlays and report a warning/findings.
+    printf '{"schema":2}\n' > "$record"
+    expect_status 1 'registry use failure keeps overlay' rgt use-nuget "$rr" "$version"
+    { [ -f "$rs/env" ] && grep -Fq WARNING "$root/stderr"; } || failed 'registry failed use lost overlay/warning'
+    cp "$root/registry-good" "$record"
+    rgt restore "$rr" > "$root/output"
+    expect_status 0 'clean removes stamp record' rgt clean --stamp "$version" --apply
+    [ ! -e "$rf/stamps/$version" ] && [ ! -e "$rf/nuget/Cratis.Registry.$version.nupkg" ] || failed 'clean retained stamp record/artifacts'
+    [ -e "$rf/nuget/Cratis.Legacy.$legacy.nupkg" ] || failed 'registry clean removed another stamp'
+    self_test_registry_invalid
+}
+
+self_test_registry_invalid() {
+    local fixture rf bad_record other=1.2.3-train.gabcdef0
+    for fixture in clean-scoped restore-other restore-no-node restore-own finish list; do
+        rf=$root/registry-invalid-$fixture
+        bad_record=$rf/stamps/$other/record.json
+        mkdir -p "$rf/nuget" "${bad_record%/*}"
+        printf '{broken\n' > "$bad_record"
+        : > "$rf/nuget/Cratis.Test.$version.nupkg"
+        rgt use-nuget "$rr" "$version" > "$root/output"
+        if [ "$fixture" = restore-own ]; then
+            bad_record=$rf/stamps/$version/record.json
+            printf '{broken\n' > "$bad_record"
+        fi
+        cp "$bad_record" "$root/invalid-before"
+        case "$fixture" in
+            clean-scoped)
+                rgt restore "$rr" > "$root/output"
+                expect_status 0 'registry invalid other record clean scoped' rgt clean --stamp "$version" --apply
+                [ ! -e "$rf/stamps/$version" ] && [ ! -e "$rf/nuget/Cratis.Test.$version.nupkg" ] || failed 'invalid other record blocked scoped clean'
+                expect_status 2 'registry invalid record clean all' rgt clean --all --apply
+                expect_status 2 'registry invalid record clean default' rgt clean --apply
+                ;;
+            restore-other)
+                expect_status 0 'registry invalid other record restore' rgt restore "$rr"
+                ;;
+            restore-no-node)
+                if PATH=/usr/bin:/bin:/usr/sbin:/sbin command -v node > /dev/null 2>&1; then
+                    printf 'SKIP: restore without node needs a system PATH without node\n' >&2; skipped=$((skipped + 1))
+                    rgt restore "$rr" > "$root/output"
+                else
+                    expect_status 0 'registry restore without node restores the overlay' env -i HOME="$home" PATH=/usr/bin:/bin:/usr/sbin:/sbin TMPDIR="$TMP" CRATIS_LOCAL_FEED="$rf" NUGET_PACKAGES="$root/registry-cache" /bin/bash "$SELF" restore "$rr"
+                    { [ ! -e "$rs/env" ] && grep -Fq 'WARNING: node not found' "$root/stderr"; } || failed 'restore without node kept overlay or missed warning'
+                fi
+                ;;
+            restore-own)
+                expect_status 1 'registry invalid own record restore' rgt restore "$rr"
+                { grep -Fq 'WARNING:' "$root/stderr" && grep -Fq "$bad_record" "$root/stderr"; } || failed 'restore missing invalid record warning'
+                ;;
+            finish)
+                expect_status 1 'registry finish skips invalid' rgt finish --task "$rt" --apply
+                record=$rf/stamps/$version/record.json rg_assert finished "$version" "$rr" "$rs" || failed 'finish skipped valid record'
+                { grep -Fq 'WARNING:' "$root/stderr" && grep -Fq "$bad_record" "$root/stderr"; } || failed 'finish missing invalid record warning'
+                rgt restore "$rr" > "$root/output"
+                ;;
+            list)
+                expect_status 1 'list invalid record' rgt list --json
+                node - "$root/output" "$version" "$other" <<'NODE' || failed 'list missing valid/invalid rows'
+const fs = require('node:fs'); const [file, valid, invalid] = process.argv.slice(2);
+const rows = JSON.parse(fs.readFileSync(file, 'utf8')).stamps;
+if (rows.length !== 2 || rows.find(r => r.stamp === valid)?.recorded !== true ||
+    rows.find(r => r.stamp === invalid)?.recorded !== 'invalid' || typeof rows.find(r => r.stamp === invalid)?.error !== 'string') process.exit(1);
+NODE
+                expect_status 1 'list invalid record text' rgt list
+                { grep -Fq invalid "$root/output" && grep -Fq "$version" "$root/output"; } || failed 'text list missing valid/invalid rows'
+                rgt restore "$rr" > "$root/output"
+                ;;
+        esac
+        [ ! -e "$rs/env" ] && [ ! -e "$rs/Directory.Packages.props" ] || failed 'invalid record prevented overlay restore'
+        cmp -s "$bad_record" "$root/invalid-before" || failed 'invalid record rewritten'
+    done
+}
+
+self_test_private_cache() {
+    local pc_repo=$root/'private cache repo' pc_feed=$root/private-feed pc_shared=$root/private-shared
+    local pc_cache pc_session pc_opt=0 other=1.2.5-train.g1234567
+    mkdir -p "$pc_repo" "$pc_feed/nuget"
+    git -C "$pc_repo" init -q
+    cp "$repo/Directory.Packages.props" "$pc_repo/Directory.Packages.props"
+    git -C "$pc_repo" add Directory.Packages.props
+    git -C "$pc_repo" -c user.email=test@example.invalid -c user.name='Private cache fixture' commit -qm initial
+    pc_cache=$(git -C "$pc_repo" rev-parse --absolute-git-dir)/cratis-local-nuget
+    pc_session=$(git -C "$pc_repo" rev-parse --absolute-git-dir)/cratis-local
+    pct() { env -i HOME="$home" PATH="$system_path" TMPDIR="$TMP" CRATIS_LOCAL_FEED="$pc_feed" NUGET_PACKAGES="$pc_shared" CRATIS_LOCAL_PRIVATE_CACHE="$pc_opt" /bin/bash "$SELF" "$@"; }
+    : > "$pc_feed/nuget/Cratis.Test.$version.nupkg"
+    expect_status 0 'private-cache default unchanged' pct use-nuget "$pc_repo" "$version"
+    [ ! -e "$pc_cache" ] && [ ! -e "$pc_session/nuget-cache" ] || failed 'private-cache default created a cache'
+    has 'Optional per-worktree cache' "$root/output" || failed 'private-cache default hint changed'
+    pct restore "$pc_repo" > "$root/output"
+    expect_status 0 'private-cache dry-run' pct --dry-run use-nuget "$pc_repo" "$version" --private-cache
+    [ ! -e "$pc_cache" ] && [ ! -e "$pc_session/nuget-cache" ] || failed 'private-cache dry-run wrote a cache'
+    expect_status 0 'private-cache env export' pct use-nuget "$pc_repo" "$version" --private-cache
+    env -i PATH=/usr/bin:/bin /bin/bash -c "source \"\$1\"; [ \"\$NUGET_PACKAGES\" = \"\$2\" ]" _ "$pc_session/env" "$pc_cache" || failed 'private-cache env does not export gitdir cache'
+    if has 'Optional per-worktree cache' "$root/output"; then failed 'private-cache still prints manual hint'; fi
+    pc_marker() { [ "$(cat "$pc_cache/.cratis-local-cache")" = "$pc_repo" ] && [ "$(cat "$pc_session/nuget-cache")" = "$pc_cache" ]; }
+    expect_status 0 'private-cache marker' pc_marker
+    expect_status 2 'private-cache live kept' pct clean "$pc_repo" --private-cache --apply
+    [ -d "$pc_cache" ] || failed 'private-cache live cache removed'
+    pct restore "$pc_repo" > "$root/output"
+    [ -f "$pc_session/nuget-cache" ] && [ -d "$pc_cache" ] || failed 'private-cache restore removed cache'
+    mkdir -p "$pc_cache/cratis.test/$version" "$pc_cache/cratis.test/$other" "$pc_cache/cratis.test/1.2.3" "$pc_cache/cratis.test/1.2.3-local.keep"
+    mkdir -p "$pc_shared/cratis.test/$version" "$pc_shared/cratis.test/$other" "$pc_shared/cratis.test/1.2.3"
+    expect_status 0 'private-cache clean scoped' pct clean --stamp "$version" --apply
+    [ ! -e "$pc_cache/cratis.test/$version" ] && [ -d "$pc_cache/cratis.test/$other" ] && [ -d "$pc_cache/cratis.test/1.2.3" ] && [ -d "$pc_cache/cratis.test/1.2.3-local.keep" ] || failed 'private-cache stamp scope violated'
+    [ ! -e "$pc_shared/cratis.test/$version" ] || failed 'private-cache shared local version retained'
+    expect_status 0 'private-cache shared cache only local' pct clean --all --apply
+    [ ! -e "$pc_shared/cratis.test/$other" ] && [ -d "$pc_shared/cratis.test/1.2.3" ] || failed 'private-cache shared non-local folder removed'
+    rm -- "$pc_cache/.cratis-local-cache"
+    mkdir -p "$pc_shared/cratis.test/$version"
+    expect_status 2 'private-cache unmarked refused' pct clean --stamp "$version" --apply
+    [ -d "$pc_shared/cratis.test/$version" ] || failed 'private-cache unmarked refusal mutated shared cache'
+    printf '%s\n' "$root/other-repo" > "$pc_cache/.cratis-local-cache"
+    expect_status 2 'private-cache mismatched marker refused' pct clean --all --apply
+    printf '%s\n' "$pc_repo" > "$pc_cache/.cratis-local-cache"
+    mv "$pc_cache" "$pc_cache.saved"; ln -s "$pc_cache.saved" "$pc_cache"
+    expect_status 2 'private-cache symlink refused' pct clean --apply
+    rm -- "$pc_cache"; mv "$pc_cache.saved" "$pc_cache"
+    printf '%s\n' "$pc_shared" > "$pc_session/nuget-cache"
+    expect_status 2 'private-cache outside gitdir refused' pct clean --apply
+    printf '%s\n' "$pc_cache" > "$pc_session/nuget-cache"
+    printf '<Project><!-- %s --></Project>\n' "$other" > "$pc_repo/Directory.Packages.props"
+    expect_status 2 'private-cache restored manifest live kept' pct clean "$pc_repo" --private-cache --stamp "$version" --apply
+    cp "$repo/Directory.Packages.props" "$pc_repo/Directory.Packages.props"
+    expect_status 0 'private-cache whole dry-run' pct clean "$pc_repo" --private-cache
+    [ -d "$pc_cache" ] && [ -f "$pc_session/nuget-cache" ] || failed 'private-cache whole dry-run mutated cache'
+    expect_status 0 'private-cache whole removal' pct clean "$pc_repo" --private-cache --apply
+    [ ! -e "$pc_cache" ] && [ ! -e "$pc_session/nuget-cache" ] && [ -d "$pc_shared/cratis.test/1.2.3" ] || failed 'private-cache whole removal scope violated'
+    : > "$pc_feed/nuget/Cratis.Test.$version.nupkg"
+    pc_opt=1
+    expect_status 0 'private-cache environment opt-in' pct use-nuget "$pc_repo" "$version"
+    pc_marker || failed 'private-cache environment opt-in missing marker'
+    pct restore "$pc_repo" > "$root/output"
+    pct clean "$pc_repo" --private-cache --apply > "$root/output"
+}
+
 self_test_base_version() {
     local base mode actual status
     for mode in local train; do
@@ -2264,7 +3177,7 @@ self_test_live_clean() {
     git -C "$lr" add Directory.Packages.props
     git -C "$lr" -c user.email=test@example.invalid -c user.name='Live clean fixture' commit -qm initial
     ls=$(git -C "$lr" rev-parse --absolute-git-dir)/cratis-local
-    lct() { env -i HOME="$home" PATH=/usr/bin:/bin:/usr/sbin:/sbin TMPDIR="$TMP" CRATIS_LOCAL_FEED="$lf" NUGET_PACKAGES="$root/live-cache" /bin/bash "$SELF" "$@"; }
+    lct() { env -i HOME="$home" PATH="$system_path" TMPDIR="$TMP" CRATIS_LOCAL_FEED="$lf" NUGET_PACKAGES="$root/live-cache" /bin/bash "$SELF" "$@"; }
     : > "$lf/nuget/Cratis.Live.$lv.nupkg"
     : > "$lf/nuget/Cratis.Unused.$uv.nupkg"
     mkdir -p "$root/live-cache/cratis.live/$lv" "$root/live-cache/cratis.live/5.0.0"
@@ -2604,7 +3517,7 @@ self_test_matrix() {
     self_test_composition
 }
 
-# Legacy mutations must work without Node and with system/configured symlink parents.
+# Registry paths allow system/configured symlink parents of the feed.
 self_test_symlink_feed() {
     local physical=$root/feed-physical-parent alias=$root/feed-symlink-parent
     local sr=$root/feed-symlink-repo sv=1.2.3-local.202610240544.gabcdef0
@@ -2615,7 +3528,7 @@ self_test_symlink_feed() {
     printf '<Project><ItemGroup><PackageVersion Include="Cratis.Symlink" Version="1.2.3"/></ItemGroup></Project>\n' > "$sr/Directory.Packages.props"
     git -C "$sr" add .gitignore Directory.Packages.props
     git -C "$sr" -c user.email=test@example.invalid -c user.name='Symlink feed fixture' commit -qm initial
-    slf() { env -i HOME="$home" PATH=/usr/bin:/bin:/usr/sbin:/sbin TMPDIR="$TMP" CRATIS_LOCAL_FEED="$alias/missing/feed" CRATIS_LOCAL_SESSION_DIR="$sr/.ai-work/local-packages" /bin/bash "$SELF" "$@"; }
+    slf() { env -i HOME="$home" PATH="$system_path" TMPDIR="$TMP" CRATIS_LOCAL_FEED="$alias/missing/feed" CRATIS_LOCAL_SESSION_DIR="$sr/.ai-work/local-packages" /bin/bash "$SELF" "$@"; }
     expect_status 0 'symlink feed resolution does not create a missing feed' slf check "$sr"
     [ ! -e "$physical/missing" ] || failed 'symlink feed resolution created directories'
     mkdir -p "$physical/missing/feed/nuget"
@@ -2767,6 +3680,16 @@ JSON
     expect_status 1 'composition malformed assets' cst verify-assets "$cr" --composition "$cm"
     cp "$root/composition-assets.json" "$cr/obj/project.assets.json"
     expect_status 0 'composition activation with transitive pinning' cst use-nuget "$cr" --composition "$cm" --pin-transitive
+    composition_registry() {
+        node - "$cf" "$cr" "$a" "$b" "$c" <<'NODE'
+const fs = require('node:fs'), path = require('node:path'); const [feed,repo,...stamps] = process.argv.slice(2);
+for (const stamp of stamps) {
+    const r = JSON.parse(fs.readFileSync(path.join(feed,'stamps',stamp,'record.json')));
+    if (r.schema !== 1 || r.consumers.length !== 1 || r.consumers[0].worktree !== repo || r.consumers[0].ecosystem !== 'nuget') process.exit(1);
+}
+NODE
+    }
+    expect_status 0 'registry composition consumer' composition_registry
     output=$cr/.ai-work/local-packages/composition
     grep -Fq 'CentralPackageTransitivePinningEnabled>true' "$output/Directory.Packages.props" || failed 'composition pin property'
     self_test_nuget_overlay "$output" Cratis.Stage "$c"
@@ -2802,6 +3725,23 @@ JSON
     expect_status 0 'composition repeated restore' cst restore "$cr"
     [ ! -e "$output" ] || failed 'composition overlay survives restore'
     cmp -s "$cr/Directory.Packages.props" "$root/composition-original.props" || failed 'composition consumer props mutated'
+    # Whole-cache cleanup also cleans feed artifacts. Keep this fixture's feed
+    # separate so the recovery fixtures below retain their declared packages.
+    local composition_feed=$cf composition_cache
+    cf=$root/private-composition-feed
+    mkdir -p "$cf/nuget"
+    cp "$composition_feed/nuget/"*.nupkg "$cf/nuget/"
+    expect_status 0 'private-cache composition' cst use-nuget "$cr" --composition "$cm" --private-cache
+    composition_cache=$(git -C "$cr" rev-parse --absolute-git-dir)/cratis-local-nuget
+    env -i PATH=/usr/bin:/bin /bin/bash -c "source \"\$1\"; [ \"\$NUGET_PACKAGES\" = \"\$2\" ]" _ "$output/env" "$composition_cache" || failed 'private-cache composition env export'
+    [ "$(cat "$cr/.ai-work/local-packages/nuget-cache")" = "$composition_cache" ] && [ "$(cat "$composition_cache/.cratis-local-cache")" = "$cr" ] || failed 'private-cache composition marker'
+    expect_status 2 'private-cache composition live kept' cst clean "$cr" --private-cache --apply
+    expect_status 0 'private-cache composition restore' cst restore "$cr"
+    [ -d "$composition_cache" ] || failed 'private-cache composition restore removed cache'
+    expect_status 0 'private-cache composition removal' cst clean "$cr" --private-cache --apply
+    [ ! -e "$composition_cache" ] && [ ! -e "$cr/.ai-work/local-packages/nuget-cache" ] || failed 'private-cache composition removal left cache registration'
+    cf=$composition_feed
+    [ -f "$cf/nuget/Cratis.Chronicle.InProcess.$a.nupkg" ] && [ -f "$cf/nuget/Cratis.Screenplay.$b.nupkg" ] && [ -f "$cf/nuget/Cratis.Stage.$c.nupkg" ] || failed 'private-cache composition cleanup removed recovery feed packages'
     # Every live mutation boundary is exercised both as an ordinary failure and
     # an uncatchable parent/child interruption, then recovered by the next call.
     for kind in fail interrupt; do
@@ -2859,7 +3799,26 @@ JSON
     passed=$((passed + 1))
 }
 
+TASK=''
+case "$MODE" in
+    pack-nuget|pack-npm|use-nuget|use-npm|finish)
+        TASK=${CRATIS_LOCAL_TASK:-}
+        ARGS=()
+        while [ $# -gt 0 ]; do
+            if [ "$1" = --task ]; then
+                [ $# -ge 2 ] || die '--task requires an ID'
+                TASK=$2; [ -n "$TASK" ] || die 'invalid task ID'; shift 2
+            else ARGS+=("$1"); shift; fi
+        done
+        set -- ${ARGS[@]+"${ARGS[@]}"}
+        if [ -n "$TASK" ]; then [[ "$TASK" =~ ^[A-Za-z0-9][A-Za-z0-9._#:/-]{0,127}$ ]] || die 'invalid task ID'; fi ;;
+esac
 case "$MODE" in
+    list) registry list "$@" ;;
+    finish)
+        [ -n "$TASK" ] || die 'finish requires --task ID or CRATIS_LOCAL_TASK'
+        [ $# -eq 0 ] || { [ $# -eq 1 ] && [ "$1" = --apply ]; } || die 'finish accepts --task ID and --apply'
+        if [ "${1:-}" = --apply ] && [ "$DRY" -eq 0 ]; then registry_update finish --apply; else registry finish; fi ;;
     stamp) stamp "$@" ;;
     plan) plan_command "$@" ;;
     closure) closure "$@" ;;