@6reduk/workspace-pipeline 0.6.0 → 0.7.0

package/README.md

@@ -1,5 +1,18 @@
 # Workspace Pipeline CLI
 
+## Desired-state installation (0.7.0 release candidate)
+
+The working tree adds manifest schema 2: ordinary `setup --source ... --adapters ...`
+creates `workspace.json` after confirmation; `update` uses it without a separate
+preview file. Whole-owned adapter contents are replaced, including custom files;
+backups are opt-in with `--backup`. Shared configurations change only declared fields.
+See [setup, update, doctor and source authoring](docs/desired-state.md).
+This is not in the published 0.6.0 package. The sections below describe the legacy
+release and explicit recovery routes; do not mix their backup/preview contracts
+with schema 2.
+
+## Published legacy lifecycle
+
 Everyday update: `workspace-pipeline update --workspace <directory>` shows the
 changes and asks for confirmation. Use `--yes` for unattended application or
 `--preview --json` to retain the advanced saved-plan workflow. See
@@ -77,7 +90,7 @@ Startup cleanup is disabled unless the user enables a local policy via
 that policy; public setup/update uses the same coordinator. Policy commands only
 write `.pipeline/retention.json`, never harness settings or project documents.
 Repository init/adopt previews acquire the explicitly selected Git pipeline source;
-remote access additionally requires `--network`. No command launches MCP or changes
+remote acquisition follows the selected source without an extra flag. No command launches MCP or changes
 credentials. Repository setup and provider activation are separate steps.
 See [repository commands](docs/repositories.md), [recovery](docs/repository-recovery.md)
 and [manual recovery boundaries](docs/repository-manual-recovery.md).

package/docs/desired-state.md

@@ -0,0 +1,243 @@
+# Install and update a workspace pipeline
+
+Development status: these commands require the unreleased 0.7.0 desired-state build,
+not the published 0.6.0 package. `workspace-pipeline` below means that build's
+installed executable. During development use `node <cli-repository>/src/cli.js`.
+Do not run these examples against a real workspace until the migration is reviewed.
+
+## What is installed
+
+A Git repository contains a schema-2 `pipeline.json` (or YAML equivalent). It
+declares which files to deliver and which named configuration fields to set or
+remove. The CLI does not run scripts from the pipeline source.
+
+The wrapper is an existing directory containing your project repository or
+repositories. The CLI configures the wrapper, not the game/application code.
+It does not move, clone, initialize or delete project repositories in this route.
+Create the directory first and place your repositories where you intend them to live.
+
+## First installation — no prepared JSON file required
+
+Example with a committed local pipeline source:
+
+```powershell
+workspace-pipeline setup --workspace "C:\Work\Game" --source "C:\Sources\my-pipeline" --subdirectory pipelines/unity --adapters codex,claude-grok
+```
+
+Use actual adapter IDs declared by your source. Unity currently supplies `codex`
+and `claude-grok`; the latter delivers Claude files for both harnesses. Kimi is
+deferred. Native plugins are not installed by this command.
+
+`--source` also accepts an HTTPS or SSH Git URL. Git authentication remains yours;
+never place tokens or passwords in the URL. A relative local source path is resolved
+from the shell's current directory, then stored relative to the wrapper. A local
+source on another Windows volume is not supported by the current source schema.
+Only committed Git contents are used, not uncommitted edits. `--ref` defaults to
+`HEAD`, and `--subdirectory` to `.`. Fetching the selected remote source is part of
+preparation; no separate network authorization flag is required. Setup, update and reset may fetch the configured remote Git source
+before confirmation of workspace changes.
+
+By default the layout is one repository named `game` at `project`, with documentation
+at `project/docs`. The displayed summary shows these choices before confirmation.
+Override them when the actual structure differs:
+
+```powershell
+workspace-pipeline setup --workspace "C:\Work\Game" --source "C:\Sources\my-pipeline" --adapters codex --repository game=game-repo --documentation game=docs
+```
+
+For multiple repositories, repeat `--repository` and explicitly bind documentation:
+
+```powershell
+workspace-pipeline setup --workspace "C:\Work\Platform" --source "C:\Sources\platform-pipeline" --adapters codex --repository api=services/api --repository docs=knowledge --documentation docs=.
+```
+
+Repository and documentation paths are relative and use `/` for separators. IDs
+are lookup keys, not inferred project types. Repository paths must not overlap.
+The CLI saves the resulting declaration as `workspace.json` only after confirmation.
+It is a source/layout configuration, not an execution preview. Existing
+`workspace.json` is not overwritten by `setup --source`; use the installed binding
+with ordinary `setup`/`update`, or explicitly edit the declaration for a supported
+change. Pipeline-ID switching is not implemented in the new engine.
+
+## Update and customization loss
+
+```powershell
+workspace-pipeline doctor --workspace "C:\Work\Game"
+workspace-pipeline update --workspace "C:\Work\Game"
+workspace-pipeline update --workspace "C:\Work\Game" --backup
+```
+
+`update` resolves the Git ref saved in `workspace.json`, shows affected paths and
+configuration changes, and asks for confirmation. Enter or an answer other than
+`y`, `yes`, `д`, `да` cancels. `--yes` authorizes unattended application; noninteractive
+use otherwise requires `--preview`. `--json` changes presentation, not authorization.
+
+There is **no backup by default**. A whole-owned directory is replaced with the
+declared contents: extra files inside it are removed and modified delivered files
+are overwritten. Owned single files are replaced individually. Other directories
+are not implicitly owned. Only declared fields of shared JSON/TOML configs change;
+credentials, models and unrelated fields are preserved. Obsolete recorded targets
+are retired on update. Invalid paths, links, malformed settings and unavailable
+sources are errors, not customization conflicts to bypass.
+
+`--backup` saves affected old adapter files/local configuration under
+`.pipeline/backups/desired-*`. A requested global backup stays inside the relevant
+user profile. Paths are reported. These backups may contain secrets: keep them local.
+If requested backup fails, replacement does not proceed.
+
+Global changes are explicitly displayed with their resolved user path and affect
+other workspaces. Unity's Claude/Grok adapter sets five user-wide Grok Claude
+compatibility flags; it does not change account/model credentials or grant trust.
+
+## Doctor, preview and interrupted work
+
+`doctor` lists extra, modified and missing delivered files, unsafe paths and differing
+configuration fields. It displays the recorded Git source, revision and digest.
+For Git-bound installations it also reports a missing, invalid or changed
+`workspace.json` (source, layout and recorded adapter selection). Repository roots
+from the installation and a valid current declaration remain protected. Changing
+the declaration is reported as drift, not silently accepted as an installed state.
+Older records without adapter IDs cannot verify selection equality; records without
+Git binding retain file/config-only inspection.
+It does not fetch updates or certify source trust, native skill discovery, MCP or
+runtime execution. Version labels do not require rewriting project documentation.
+
+`setup ... --preview --json` and `update ... --preview --json` inspect without applying
+or creating the descriptor. In schema 2 this is an observation, **not** a saved-plan
+authorization accepted by `--apply`. The old `--apply --preview <file>` route is
+retained for schema-1/legacy operations only; a schema-2 replayable-plan route is
+not implemented. Normal schema-2 use needs neither external file nor `--apply`.
+
+Replacement is not atomic across all files and has no automatic rollback. After a
+failure, inspect the reported partial state and `doctor`. The pending record binds
+the same Git revision/digest; retry must use that same source and selection. If a
+branch moved, the new revision is refused as a retry; `reset` can reacquire the
+recorded commit instead (see below). Do not delete pending records
+or locks to force success. For an abandoned lock use the bounded recovery command
+below; old legacy recovery commands do not apply to these records.
+The schema-2 switch command route is not yet implemented;
+legacy commands are not a substitute. These are release limitations, not a claim
+that the entire migration is finished.
+
+## Reset to the installed version
+
+```powershell
+workspace-pipeline reset --workspace "C:\Work\Game"
+workspace-pipeline reset --workspace "C:\Work\Game" --backup
+```
+
+The default is the recorded installed Git commit, **not latest**. Reset reacquires
+that commit from the saved source and checks its recorded digest before changing
+anything. It restores delivered files and named settings and removes extra files
+inside owned directories. It uses the same confirmation and optional backup rules
+as update. `--preview --json` only displays the proposed effect.
+
+Use `update` to move to the current source ref. Reset leaves `workspace.json`
+unchanged, so later updates still follow that ref. If the declaration's source,
+adapter selection or layout changed, reset refuses rather than guessing which
+mapping to restore. Missing binding/adapter metadata or unavailable historical Git
+objects likewise prevents reset before replacement. This is not an offline backup
+restore. No project files are reset and no Git checkout/reset is performed.
+
+After a handled installation interruption, reset restores the pending installation's
+recorded commit even if its branch moved. It does not cancel an unfinished removal,
+erase pending metadata or release a stale lock. Global named settings can be
+restored just as during update, with the shared effect displayed before consent.
+
+## Recover an abandoned lock after process termination
+
+```powershell
+workspace-pipeline recover-lock --workspace "C:\Work\Game"
+# Only when the reported global Grok lock belongs to this workspace:
+workspace-pipeline recover-lock --workspace "C:\Work\Game" --global
+```
+
+This command does not kill processes, resume installation or modify configuration.
+It verifies the lock's purpose/workspace, checks that its PID is absent on the same
+host, displays the target and asks for confirmation (`--yes` for unattended use).
+`--preview --json` is read-only. A live/reused PID, unknown host, malformed or older
+owner format, missing owner, links, foreign entries or a conflicting repository
+operation prevent recovery. Lock age alone is never sufficient.
+
+The exact stale directory is renamed to a temporary sibling, its owner identity
+is rechecked, and its owner file and directory are deleted nonrecursively. No
+lock archive is retained after success. Pending operation records remain intact.
+Run doctor and explicitly retry reset (installation) or remove (removal) afterward.
+No automatic retry is performed.
+
+Recoverers are serialized using the existing OS lease (Windows/Linux only).
+After the atomic rename, recovery never touches the original lock path again:
+a new writer may already own it. If deletion fails, the error reports
+`lockReleased: true` and `residualPath` for inspection. A process crash after
+rename can leave a `*-retiring-<uuid>` sibling; it is not an active lock, and
+recovery does not automatically sweep such leftovers or older recovered-lock
+archives. No recursive cleanup or archive-retention command is provided.
+
+These are cooperative-process safeguards, not isolation against hostile concurrent
+filesystem mutation. Empty/partially written owners and old token-only global locks
+need separate inspection, not a force-unlock flag. Source/package corruption and
+partially written configuration are not repaired by lock recovery.
+
+## Remove and reinstall
+
+```powershell
+workspace-pipeline remove --workspace "C:\Work\Game"
+workspace-pipeline update --workspace "C:\Work\Game"
+```
+
+`remove` operates offline on the recorded installation, displays its scope and asks
+for confirmation (`--yes` for unattended use). It removes the entire delivery,
+including custom files in owned directories, and its named local configuration
+fields. It does not need the Git source. `--backup` is optional, off by default.
+`--preview --json` observes the removal without applying it.
+
+Project repositories, unrelated config fields, `workspace.json`, existing journals
+and backups are preserved. Shared user-wide Grok compatibility is deliberately
+left unchanged because other workspaces may use it. Remove does not uninstall
+native plugins or erase unknown/unrecorded old adapters. It does not support partial
+provider selection. Missing/invalid ownership, unsafe paths and malformed shared
+configuration cause refusal, not an unrestricted directory wipe.
+
+Doctor then reports `not-installed`. Ordinary `update` or `setup` reinstalls using
+the retained source declaration. A handled interruption during removal can be
+continued with the same `remove` command; installation/update cannot replace its
+unfinished marker. Conversely, finish an interrupted installation before removing
+it. After a hard kill, recover abandoned locks first using the separate command.
+
+## For pipeline authors
+
+```json
+{
+  "schemaVersion": 2,
+  "id": "example",
+  "version": "1.0.0",
+  "files": [{"source": "core", "target": ".example", "kind": "directory"}],
+  "adapters": {
+    "codex": {
+      "providers": ["codex"],
+      "files": [{"source": "instructions.md", "target": "AGENTS.md", "kind": "file"}],
+      "settings": []
+    }
+  }
+}
+```
+
+Top-level files are shared and installed once. Adapter files/settings are selected
+by adapter ID; a provider cannot occur twice in a selection. Source directories
+must contain committed files; Git does not supply empty directories. Targets cannot
+overlap each other, repositories, CLI metadata, `workspace.json`, or whole shared
+configuration files. Field declarations use `target`, JSON-pointer `pointer`,
+`operation: set|remove` and a value only for `set`.
+
+Supported configuration targets are `codex.workspace` (named agents/MCP),
+`claude.workspace` (`enabledMcpjsonServers`), `claude.mcp` (named MCP),
+`grok.workspace` (named MCP), and `grok.user` (five Claude compatibility booleans).
+They map to CLI-defined paths; sources cannot provide arbitrary home filenames.
+Hooks, credentials, model settings and executable installer extensions are outside
+this configuration contract. Review delivered MCP commands before trusting a source.
+
+Keep canonical rules in shared files and provider discovery files small. Validate
+relative links in the installed layout, not just in the source repository. Test
+fresh install, update after custom changes, removed upstream targets, optional
+backup, interruption, and doctor using disposable profiles and the packed CLI.
+Package checks are not human approval or proof of model behavior.

package/docs/lifecycle-cli.md

@@ -1,5 +1,10 @@
 # Lifecycle CLI routing — development scope
 
+This page describes schema-1 legacy operations and their saved-plan/recovery
+contract. For the new schema-2 desired-state setup/update (no mandatory preview,
+no default backup), see [the desired-state guide](desired-state.md). Do not apply
+the legacy conflict/backup/launcher rules below to the new installer.
+
 The generic dispatcher routes `setup`, `update`, `repair`, `remove`, `switch` and `continue` through
 the native operation APIs and their coordinators. The packaged entrypoint supplies
 compiled Codex, Claude, Kimi and Grok adapters. S11 review and native Kimi/Grok
@@ -63,8 +68,8 @@ The temporary preview is not a replacement for durable recovery evidence.
 Once a trusted registry is provided by the CLI assembly:
 
 ```text
-workspace-pipeline setup --workspace <absolute-wrapper> [--manifest <absolute-file>] [--network]
-workspace-pipeline update --workspace <absolute-wrapper> [--manifest <absolute-file>] [--network]
+workspace-pipeline setup --workspace <absolute-wrapper> [--manifest <absolute-file>]
+workspace-pipeline update --workspace <absolute-wrapper> [--manifest <absolute-file>]
 workspace-pipeline setup --workspace <absolute-wrapper> --apply --preview <absolute-json-file>
 workspace-pipeline update --workspace <absolute-wrapper> --apply --preview <absolute-json-file>
 ```
@@ -72,7 +77,7 @@ workspace-pipeline update --workspace <absolute-wrapper> --apply --preview <abso
 Preview displays a human-readable summary by default. Add `--json` to return
 the complete prepared JSON on stdout for saving and subsequent apply. It may acquire a Git
 source into temporary storage outside the wrapper, but does not write provider
-configuration. Network acquisition requires explicit `--network`. When manifest
+configuration. Remote Git acquisition follows the selected source. When manifest
 is omitted, setup uses the standard workspace manifest; update uses the recorded
 manifest origin. Relocation does not silently rebind it. Use the explicit
 [manifest rebind workflow](rebind.md) to change that origin.
@@ -80,7 +85,7 @@ manifest origin. Relocation does not silently rebind it. Use the explicit
 Save prepared JSON privately, inspect its operations and then explicitly invoke
 `--apply --preview`. It may contain configuration secrets and absolute local
 paths; do not commit it or send it to shared logs. Apply does not accept
-`--manifest` or `--network`, acquire a fresh source, or substitute a new preview.
+`--manifest`, acquire a fresh source, or substitute a new preview.
 Missing/stale staged data is an error, not permission to download replacements.
 
 Apply binds the verb and exact wrapper before lock acquisition, then invokes
@@ -147,7 +152,7 @@ Removal preserves other installed providers and shared files while needed; full
 removal restores taken-over content and removes only owned scope. Missing/corrupt
 snapshots, backups, unresolved history or conflicting user edits fail closed.
 Neither route reads the original manifest or downloads from Git. `--manifest`
-and `--network` are rejected. `--providers` and `--bundles` are remove-preview-only;
+is rejected. `--providers` and `--bundles` are remove-preview-only;
 omitting both previews all installed providers and bundles. Use actual installed
 bundle IDs; selecting a bundle member via `--providers` fails with
 `remove.bundle-required`. The saved subject fixes the actual selection, so apply
@@ -168,7 +173,7 @@ Interrupted-operation continuation has a separate exact approval boundary below.
 With the same trusted built-in registry restriction:
 
 ```text
-workspace-pipeline switch --workspace <absolute-wrapper> --manifest <absolute-incoming-manifest> [--network]
+workspace-pipeline switch --workspace <absolute-wrapper> --manifest <absolute-incoming-manifest>
 workspace-pipeline switch --workspace <absolute-wrapper> --apply --preview <absolute-json-file>
 ```
 

package/docs/migrations/unity.md

@@ -7,7 +7,7 @@ synthetic testing; independent review and real deployment approval remain pendin
 
 `workspace-pipeline migration unity preview --workspace <absolute-wrapper> --manifest <absolute-manifest>`
 prepares the complete proposal, staging committed Git source outside the wrapper.
-Add `--network` only to permit remote acquisition. Keep the JSON private: it can
+Selecting a remote Git source permits acquisition during preparation. Keep the JSON private: it can
 contain full config bytes. The command does not disable plugins or install files.
 
 `workspace-pipeline migration unity inspect --workspace <absolute-wrapper> --recovery <relative-record> --phase <phase>`

package/docs/rebind.md

@@ -27,7 +27,7 @@ and `proposed.manifest`. The first command only reads local state/history and th
 new manifest. It does not fetch Git, move files, or activate the new origin.
 
 `--accept-rebind` explicitly approves the saved proposal for source acquisition.
-For a remote source, add `--network` to this second command. Inspect the resulting
+A remote source is fetched during this second command. Inspect the resulting
 update operations before the third command, which separately approves file writes.
 The new origin becomes active as part of that normal, locked update, not as a
 standalone write to `.pipeline/state.json`.

package/docs/repositories.md

@@ -29,8 +29,8 @@ workspace-pipeline wrap --workspace "C:\Work\GameWorkspace" --manifest "C:\Work\
 
 Use `--json` and save the exact JSON stdout as UTF-8 `preview.json` outside the affected repository
 and wrapper. Read its operations and blockers. Preview may acquire a temporary
-Git snapshot, but does not perform repository effects. Remote access is explicit
-with `--network`; local Git does not need that flag. Do not put credentials into
+Git snapshot, but does not perform repository effects. A selected remote source
+is fetched during preparation; local Git is read from disk. Do not put credentials into
 source URLs or retained preview files.
 
 ```powershell

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@6reduk/workspace-pipeline",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Workspace-local Git pipeline configuration dispatcher",
   "type": "module",
   "bin": {

package/schemas/pipeline-v2.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "id", "version", "adapters"],
+  "properties": {
+    "schemaVersion": {"const": 2},
+    "id": {"type": "string", "pattern": "^[a-z][a-z0-9-]{0,62}$"},
+    "version": {"type": "string", "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)$"},
+    "files": {"$ref": "#/properties/adapters/additionalProperties/properties/files"},
+    "adapters": {
+      "type": "object", "minProperties": 1,
+      "propertyNames": {"pattern": "^[a-z][a-z0-9-]{0,62}$"},
+      "additionalProperties": {
+        "type": "object", "additionalProperties": false,
+        "required": ["providers", "files", "settings"],
+        "properties": {
+          "providers": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"enum": ["codex", "claude", "grok", "kimi"]}},
+          "files": {"type": "array", "maxItems": 10000, "items": {
+            "type": "object", "additionalProperties": false,
+            "required": ["source", "target", "kind"],
+            "properties": {
+              "source": {"type": "string", "minLength": 1},
+              "target": {"type": "string", "minLength": 1},
+              "kind": {"enum": ["file", "directory"]}
+            }
+          }},
+          "settings": {"type": "array", "maxItems": 1000, "items": {
+            "type": "object", "additionalProperties": false,
+            "required": ["target", "pointer", "operation"],
+            "properties": {
+              "target": {"enum": ["codex.workspace", "claude.workspace", "claude.mcp", "grok.workspace", "grok.user"]},
+              "pointer": {"type": "string", "minLength": 2},
+              "operation": {"enum": ["set", "remove"]},
+              "value": {}
+            },
+            "allOf": [{"if": {"properties": {"operation": {"const": "set"}}}, "then": {"required": ["value"]}, "else": {"not": {"required": ["value"]}}}]
+          }}
+        }
+      }
+    }
+  }
+}

package/src/cli.js

@@ -3,6 +3,7 @@ import {providerRegistry} from './providers/registry.js';
 import {outputWriter} from './commands/output.js';
 import {createClaudeCompatibility} from './compat/claude.js';
 import {runInteractiveUpdate} from './commands/interactive-update.js';
+import {tryDesiredLifecycle} from './commands/desired-lifecycle.js';
 import {createInterface} from 'node:readline/promises';
 const write=stream=>text=>new Promise((resolve,reject)=>stream.write(text,error=>error?reject(error):resolve()));
 // Prevent an unhandled pipe error; write callbacks report delivery failures.
@@ -10,14 +11,16 @@ process.stdout.on('error',()=>{});process.stderr.on('error',()=>{});
 const args=process.argv.slice(2),json=args.includes('--json');
 const options={stdout:outputWriter(write(process.stdout),json),stderr:outputWriter(write(process.stderr),json),registry:providerRegistry,compatibility:createClaudeCompatibility()};
 try{
-  process.exitCode=await runInteractiveUpdate(args,options,{
+  const interaction={
     isTTY:Boolean(process.stdin.isTTY&&process.stderr.isTTY),display:write(process.stderr),
     confirm:async()=>{
       const rl=createInterface({input:process.stdin,output:process.stderr});
       try{return /^(y|yes|д|да)$/i.test((await rl.question('Apply these changes? [y/N] ')).trim());}
       catch{return false;}finally{rl.close();}
     }
-  });
+  };
+  const desired=await tryDesiredLifecycle(args,options,interaction);
+  process.exitCode=desired??await runInteractiveUpdate(args,options,interaction);
 }catch{
   await options.stderr(JSON.stringify({error:'cli.interactive-io',next:'Inspect doctor before retry; no automatic retry or reset.'})+'\n');process.exitCode=2;
 }

package/src/commands/desired-lifecycle.js

@@ -0,0 +1,93 @@
+import path from 'node:path';
+import {homedir} from 'node:os';
+import {ContractError,fail,parse} from '../contracts/parse.js';
+import {absoluteRoot} from '../workspace/paths.js';
+import {observeTargets} from '../operations/state.js';
+import {utf8} from '../source/inventory.js';
+import {prepareDesiredWorkspace} from '../desired-state/source.js';
+import {materializeDesiredFiles,inspectDesiredFiles} from '../desired-state/inventory.js';
+import {compileDesiredManifest} from '../contracts/desired-state.js';
+import {readDesiredRecords} from '../desired-state/records.js';
+import {includeRetiredTargets} from '../desired-state/retirement.js';
+import {prepareLocalSettings} from '../desired-state/local-settings.js';
+import {compileDesiredSettings} from '../desired-state/settings.js';
+import {applyDesiredFiles} from '../desired-state/apply-files.js';
+import {safeTerminalText as safe} from './output.js';
+import {desiredArguments,initialDescriptor} from './desired-setup.js';
+import {tryDesiredRemove} from './desired-remove.js';
+import {prepareDesiredReset} from '../desired-state/reset.js';
+import {runDesiredRecovery} from './desired-recover.js';
+
+// V2 entrypoint; null preserves the old CLI path for old descriptors. No new
+// source-supplied executable hooks, model changes or external preview required.
+export async function tryDesiredLifecycle(args,options,{isTTY=false,confirm,display,hostOptions={}}={}) {
+  if(args[0]==='recover-lock')return runDesiredRecovery(args,options,{isTTY,confirm,display,hostOptions});
+  if(args[0]==='remove')return tryDesiredRemove(args,options,{isTTY,confirm,display,hostOptions});
+  if(!['setup','update','reset'].includes(args[0]) || args.includes('--apply'))return null;
+  const at=args.indexOf('--workspace');if(at<0 || !args[at+1])return null;
+  try {
+    const workspace=absoluteRoot(args[at+1]);
+    const [entry]=await observeTargets(workspace,['workspace.json']);
+    const creating=args[0]==='setup'&&args.includes('--source');
+    if(!creating&&entry.bytes===null)return null;
+    let descriptor=entry.bytes===null?null:parse(utf8(entry.bytes),'json');
+    if(!creating&&descriptor.schemaVersion!==2)return null;
+    const parsed=desiredArguments(args),{seen}=parsed;
+    if(creating) {
+      if(entry.bytes!==null)fail('desired.setup-already-configured');
+      descriptor=initialDescriptor(workspace,parsed,{cwd:hostOptions.cwd});
+    } else if(['--source','--adapters','--ref','--subdirectory','--repository','--documentation'].some(f=>seen.has(f)))fail('cli.arguments');
+    const dry=seen.has('--preview'),yes=seen.has('--yes');
+    if(dry&&yes)fail('cli.arguments');
+    if(!dry && !yes && (!isTTY||!confirm))fail('cli.confirmation-required');
+    const records=await readDesiredRecords(workspace,{allowLegacyMigration:true});
+    if(records.pending?.value.intent==='remove')fail('desired.finish-remove-before-update');
+    // Selecting a remote Git source and requesting setup/update authorizes the
+    // source fetch, not changes to the workspace before confirmation.
+    const prepare=args[0]==='reset'?prepareDesiredReset:prepareDesiredWorkspace;
+    const prepared=await prepare(workspace,JSON.stringify(descriptor),{
+      tempRoot:hostOptions.tempRoot,network:descriptor.pipeline?.transport==='remote'});
+    const compiled=compileDesiredManifest(prepared.input.manifest,{selected:prepared.input.selected,protectedPaths:prepared.input.protectedPaths});
+    const delivered=materializeDesiredFiles(compiled,prepared.input.source);
+    const previousRoots=Object.values(records.installed?.value.binding?.layout.repositories??{}).map(r=>r.path);
+    const protectedPaths=[...new Set([...prepared.input.protectedPaths,...previousRoots,...(records.legacy?.protectedPaths??[])])];
+    compileDesiredManifest(prepared.input.manifest,{selected:prepared.input.selected,protectedPaths});
+    const retired=includeRetiredTargets(records.installed?.value??records.legacy?.ownership,compiled,delivered,protectedPaths);
+    const files=await inspectDesiredFiles(workspace,retired.desired);
+    const local=await prepareLocalSettings(workspace,retired.settings.filter(s=>s.target!=='grok.user'));
+    const globalOps=retired.settings.filter(s=>s.target==='grok.user');let global=null;
+    if(globalOps.length) {
+      const home=absoluteRoot(hostOptions.userHome??homedir());
+      const [observed]=await observeTargets(home,['.grok/config.toml']);
+      const result=compileDesiredSettings('grok.user',observed.bytes,globalOps);
+      global={path:path.join(home,'.grok/config.toml'),changed:result.changed};
+    }
+    const summary={command:args[0],workspace,pipeline:compiled.pipeline,providers:compiled.providers,
+      files,localSettings:local.map(s=>({path:s.path,changed:s.changed})),globalSettings:global,
+      backup:seen.has('--backup'),legacyMigration:Boolean(records.legacy),...(prepared.reset?{reset:prepared.reset}:{}),descriptor:{path:'workspace.json',action:creating?'create':'preserve',layout:descriptor.layout},provenance:prepared.provenance,preparation:prepared.preparation};
+    if(dry){await options.stdout(JSON.stringify({...summary,status:'preview',applied:false})+'\n');return files.ready?0:1;}
+    const lines=[`Workspace Pipeline — ${args[0]}`,`Workspace: ${safe(workspace)}`,
+      `Pipeline: ${safe(compiled.pipeline.id)} @ ${safe(compiled.pipeline.version)}`,
+      `Backup: ${summary.backup?'enabled':'OFF'}`,
+      'The entire declared adapter scope will be replaced; custom files in it will be removed.'];
+    lines.push(`workspace.json: ${creating?'create':'preserve'}`);
+    if(prepared.reset)lines.push(`Reset: ${prepared.reset.mode}, Git revision ${safe(prepared.reset.commit)} (not latest).`);
+    for(const [id,repo] of Object.entries(descriptor.layout.repositories))lines.push(`Repository ${safe(id)}: ${safe(repo.path)} (not moved or cloned)`);
+    lines.push(`Documentation: ${safe(descriptor.layout.documentation.repository)} / ${safe(descriptor.layout.documentation.path)}`);
+    for(const category of ['extra','modified','missing','blocked'])for(const item of files[category])lines.push(`  ${category}: ${safe(item.path)}`);
+    for(const item of summary.localSettings)lines.push(`  settings: ${safe(item.path)} (${item.changed?'change':'unchanged'})`);
+    if(global)lines.push(`GLOBAL settings: ${safe(global.path)} (${global.changed?'change':'unchanged'}); affects other workspaces.`);
+    if(records.legacy)lines.push('Migrate legacy installation state; preserve its record in .pipeline/history and leave existing journals unchanged.');
+    if(display)await display(lines.join('\n')+'\n');else await options.stderr(lines.join('\n')+'\n');
+    if(!files.ready)fail('desired.unsafe-target');
+    if(!yes && await confirm()!==true){await options.stdout(JSON.stringify({status:'cancelled',applied:false})+'\n');return 0;}
+    // Apply the already acquired immutable source; do not fetch again after consent.
+    const result=await applyDesiredFiles({...prepared.input,backup:summary.backup},{...hostOptions,createDescriptor:creating,migrateLegacy:Boolean(records.legacy),expectedRecords:prepared.expectedRecords});
+    await options.stdout(JSON.stringify({...result,...(prepared.reset?{reset:prepared.reset}:{}),provenance:prepared.provenance,preparation:prepared.preparation})+'\n');return 0;
+  }catch(error){
+    await options.stderr(JSON.stringify({error:error instanceof ContractError?error.code:'cli.desired-io',
+      ...(error.code==='desired.setup-already-configured'?{hint:'workspace.json already exists. Run doctor, then update using the saved declaration; do not repeat setup --source. If an installation was interrupted and the source ref moved, use reset. Finish pending removal with remove first.'}:{}),
+      ...(error.code==='desired.finish-remove-before-update'?{hint:'Finish the pending removal with remove before setup, update or reset.'}:{}),
+      ...(error.desiredState?{application:error.desiredState}:{})})+'\n');return 2;
+  }
+}

package/src/commands/desired-recover.js

@@ -0,0 +1,28 @@
+import {ContractError,fail} from '../contracts/parse.js';
+import {desiredArguments} from './desired-setup.js';
+import {inspectDesiredLock,recoverDesiredLock} from '../desired-state/lock-recovery.js';
+import {safeTerminalText as safe} from './output.js';
+
+export async function runDesiredRecovery(args,options,{isTTY=false,confirm,display,hostOptions={}}={}) {
+  try {
+    if(args.filter(a=>a==='--global').length>1)fail('cli.arguments');
+    const {seen,values}=desiredArguments(args.filter(a=>a!=='--global'));
+    if(!values.has('--workspace')||[...seen].some(f=>!['--workspace','--yes','--preview','--json'].includes(f)))fail('cli.arguments');
+    const dry=seen.has('--preview'),yes=seen.has('--yes');
+    if(dry&&yes)fail('cli.arguments');
+    if(!dry&&!yes&&(!isTTY||!confirm))fail('cli.confirmation-required');
+    const workspace=values.get('--workspace'),settings={userHome:hostOptions.userHome,global:args.includes('--global')};
+    const observed=await inspectDesiredLock(workspace,settings);
+    if(dry){await options.stdout(JSON.stringify({...observed,applied:false})+'\n');return observed.status==='owner-unconfirmed'?1:0;}
+    const text=['Workspace Pipeline — recover-lock',`Workspace: ${safe(observed.workspace)}`,
+      `Lock: ${safe(observed.path)}`,`Owner status: ${safe(observed.lock?.liveness??'absent')}`,
+      'Only stale lock metadata will be deleted; no process is killed and no installation is resumed.',
+      ...(settings.global?['GLOBAL lock: user-wide Grok config lock; configuration remains unchanged.']:[])].join('\n')+'\n';
+    if(display)await display(text);else await options.stderr(text);
+    if(observed.status==='owner-unconfirmed')fail('desired.recovery-owner-unconfirmed');
+    if(!yes&&await confirm()!==true){await options.stdout(JSON.stringify({status:'cancelled',applied:false})+'\n');return 0;}
+    await options.stdout(JSON.stringify(await recoverDesiredLock(workspace,observed,settings))+'\n');return 0;
+  }catch(error){await options.stderr(JSON.stringify({error:error instanceof ContractError?error.code:'cli.desired-recovery-io',
+    ...(error.recovery?{recovery:error.recovery}:{}),
+    next:'Inspect lock paths and pending state; do not delete unknown locks or operation records.'})+'\n');return 2;}
+}

package/src/commands/desired-remove.js

@@ -0,0 +1,48 @@
+import {ContractError,fail} from '../contracts/parse.js';
+import {absoluteRoot} from '../workspace/paths.js';
+import {observeTargets} from '../operations/state.js';
+import {readDesiredRecords,installedPath,pendingPath} from '../desired-state/records.js';
+import {prepareDesiredRemoval} from '../desired-state/removal.js';
+import {inspectDesiredFiles} from '../desired-state/inventory.js';
+import {prepareLocalSettings} from '../desired-state/local-settings.js';
+import {applyDesiredFiles} from '../desired-state/apply-files.js';
+import {desiredArguments} from './desired-setup.js';
+import {safeTerminalText as safe} from './output.js';
+
+export async function tryDesiredRemove(args,options,{isTTY=false,confirm,display,hostOptions={}}={}) {
+  if(args[0]!=='remove')return null;
+  const at=args.indexOf('--workspace');if(at<0||!args[at+1])return null;
+  try {
+    const workspace=absoluteRoot(args[at+1]);
+    const markers=await observeTargets(workspace,[installedPath,pendingPath]);
+    if(markers.every(m=>m.bytes===null))return null;
+    const {seen}=desiredArguments(args);
+    if([...seen].some(f=>!['--workspace','--preview','--yes','--json','--backup'].includes(f)))fail('cli.arguments');
+    const dry=seen.has('--preview'),yes=seen.has('--yes');
+    if(dry&&yes)fail('cli.arguments');
+    if(!dry&&!yes&&(!isTTY||!confirm))fail('cli.confirmation-required');
+    const records=await readDesiredRecords(workspace),prepared=await prepareDesiredRemoval(workspace,records);
+    if(prepared.alreadyRemoved){await options.stdout(JSON.stringify({workspace,status:'removed',applied:false,globalSettings:'preserved'})+'\n');return 0;}
+    const files=await inspectDesiredFiles(workspace,prepared.desired);
+    const local=await prepareLocalSettings(workspace,prepared.settings);
+    const summary={command:'remove',workspace,status:'preview',applied:false,files,
+      localSettings:local.map(s=>({path:s.path,changed:s.changed})),backup:seen.has('--backup'),globalSettings:'preserved',
+      preserved:['workspace.json','project repositories','.pipeline journals and backups']};
+    if(dry){await options.stdout(JSON.stringify(summary)+'\n');return files.ready?0:1;}
+    const lines=['Workspace Pipeline — remove',`Workspace: ${safe(workspace)}`,`Backup: ${summary.backup?'enabled':'OFF'}`,
+      'Remove all recorded adapter files, including custom files inside owned directories.',
+      'Preserve repositories, workspace.json, journals/backups and shared global settings.'];
+    for(const item of files.extra)lines.push(`  remove: ${safe(item.path)}`);
+    for(const item of files.blocked)lines.push(`  blocked: ${safe(item.path)}`);
+    for(const item of summary.localSettings)lines.push(`  settings: ${safe(item.path)} (${item.changed?'remove owned fields':'unchanged'})`);
+    if(display)await display(lines.join('\n')+'\n');else await options.stderr(lines.join('\n')+'\n');
+    if(!files.ready)fail('desired.unsafe-target');
+    if(!yes&&await confirm()!==true){await options.stdout(JSON.stringify({status:'cancelled',applied:false})+'\n');return 0;}
+    const result=await applyDesiredFiles({workspace,protectedPaths:prepared.protectedPaths,backup:summary.backup},
+      {...hostOptions,removeExisting:true,removalExpected:{installed:records.installed?.hash??null,pending:records.pending?.hash??null}});
+    await options.stdout(JSON.stringify({...result,workspace,preserved:summary.preserved})+'\n');return 0;
+  }catch(error){
+    await options.stderr(JSON.stringify({error:error instanceof ContractError?error.code:'cli.desired-remove-io',
+      ...(error.desiredState?{application:error.desiredState}:{})})+'\n');return 2;
+  }
+}