@6reduk/workspace-pipeline 0.3.0 → 0.5.0

package/README.md

@@ -1,11 +1,15 @@
 # Workspace Pipeline CLI
 
+Claude/Grok shared delivery: [one Claude configuration, plain Grok launch,
+global compatibility preview and recovery](docs/claude-grok.md).
+
 `@6reduk/workspace-pipeline` — workspace-local pipeline delivery. Licensed under MIT.
 
 **`--help`, read-only `doctor`, and `logs list/clean/policy` are implemented.**
 Setup/update/repair/remove/switch/continue use compiled workspace-local adapters
-for Codex, Claude, Kimi and Grok. No native plugin installation
-or global activation is performed. Claude/Grok shared-entry and skill routing were
+for Codex, Claude, Kimi and legacy native Grok. No native plugin installation
+is performed. Claude-only delivery additionally offers an explicitly approved
+user-wide Grok compatibility prerequisite. Claude/Grok shared-entry and skill routing were
 observed in disposable sessions. Kimi native verification is deferred; its
 configuration renderer remains experimental. Real-project migration requires an
 explicit preview and approval; installation is not blanket runtime certification.
@@ -15,7 +19,8 @@ manifest/source binding changes) and [reset](docs/reset.md) (backed-up restorati
 or clearing of selected local adapter configuration). Both require a separate
 preview and explicit apply for changes; these commands are not in registry 0.2.0.
 
-Grok's Claude-import suppression requires the [scoped launch command](docs/launch.md).
+Legacy native Grok's Claude-import suppression uses the [scoped launch command](docs/launch.md).
+New Claude-only delivery uses plain `grok` and deliberately enables those imports.
 File installation does not establish native session discovery or runtime isolation;
 Kimi/Grok checks and known generic-skill discovery limits are documented in
 [native component formats](docs/native-provider-format.md).
@@ -52,7 +57,9 @@ npm run pack:check
 npm run test:packed:providers
 ```
 
-The executable name is `workspace-pipeline`. Doctor prints JSON: exit 0 means
+The executable name is `workspace-pipeline`. Output is readable by default;
+add `--json` for complete machine output. Use `--json` when saving any preview
+for a later apply, even when redirecting stdout to a file. Doctor exit 0 means
 observed configuration ready, 1 means not ready/incomplete, 2 means invocation or
 transport error. Unsupported commands exit with code 2. On Windows use an absolute
 path such as `C:\Projects\my-workspace`. See [doctor](docs/doctor.md) for limits.

package/docs/claude-grok.md

@@ -0,0 +1,122 @@
+# One Claude delivery for Claude Code and Grok
+
+Select a Claude-only source bundle, such as the new Unity `claude-grok` bundle.
+The name describes its consumers; its provider list contains only `claude`.
+The source supplies one full `CLAUDE.md`, `.claude/skills`, optional
+`.claude/agents`, and `.mcp.json`. Start either `claude` or plain `grok` in the
+wrapper. Do not use the old `launch grok` command: it is only for legacy native
+Grok deliveries and disables the imports this mode needs.
+
+## What setup changes
+
+Normal setup/update/repair/reset preview now includes a **separate user-wide
+Grok prerequisite** when the desired delivery includes Claude but not native
+Grok. If Grok is absent, it is reported as `not-present`; Claude still installs.
+Old dual-provider sources retain their legacy behavior until migrated.
+
+If Grok exists, explicit apply enables only these settings in its effective user
+profile (`GROK_HOME/config.toml`, otherwise the user's `.grok/config.toml`):
+
+```toml
+[compat.claude]
+skills = true
+rules = true
+agents = true
+mcps = true
+hooks = true
+```
+
+These preferences affect **all Grok workspaces**, including user-installed
+hooks/MCP. They are not workspace isolation. Other settings, including model,
+credentials, trust, permission rules and `compat.claude.sessions`, are preserved.
+The installer never grants folder trust or starts a model/MCP session.
+
+Use the normal command with `--json` to save its complete preview, then review
+and apply that exact file. New Claude-only previews bind both the workspace
+plan and the global prerequisite. Old previews must be regenerated; do not
+manually unwrap/edit a preview to avoid its global checks.
+This includes old ordinary (non-switch) continuation previews: regenerate with
+`continue --workspace <path> --recovery <retained-record>` and approve the new
+preview. Existing recovery evidence remains unchanged; it is not a lockout.
+
+Close configuration editors while applying. Backups and operation records live
+under `<GROK_HOME>/workspace-pipeline-backups/<id>/`, **not in the workspace**.
+The reported directory contains `config.before.toml` when a file existed,
+`operation.json`, and on success `completed.json`. Backups may contain secrets;
+keep them private. They are not covered by workspace journal cleanup. Review
+and remove obsolete backup directories manually when no longer needed.
+
+## Diagnosis and repair
+
+`doctor` checks actual configuration and known overriding environment/policy
+conditions. When a native Grok executable is available it also runs bounded
+`grok inspect --json` without `--trust`, retaining only compatibility results.
+It reports native inspection separately. This does not prove model-visible
+skills, execution of agents, a working MCP connection or task acceptance.
+Untrusted workspace discovery may be incomplete; grant trust yourself in the
+harness only after reviewing the workspace.
+
+Conflicting environment overrides, managed policy files, legacy import markers,
+malformed/unsupported TOML, symlinks and stale before hashes fail closed. The CLI
+does not override organization policy or silently remove an import marker.
+An existing policy file conservatively requires separate resolution, even if
+it might not ultimately pin these five fields. A missing native binary yields
+`native: not-available`, not an invented native PASS.
+
+If the workspace operation succeeded but global configuration failed, the
+result is `needs-compatibility`, with `workspaceStatus: ready`. Workspace files
+are already installed; run a fresh **repair preview/apply**, rather than replaying
+a stale setup preview. There is no claim of a cross-filesystem atomic transaction.
+Historical switch continuations have no global approval envelope: after workspace
+activation they inspect compatibility without changing it. If needed, finish with
+a fresh repair preview/apply. Source authors must make their complete `CLAUDE.md`
+usable by either harness, not require a nonexistent Grok provider route.
+
+To inspect/enable the same prerequisite separately (for example after installing
+Grok later), use:
+
+```powershell
+workspace-pipeline compat claude --json > compat-preview.json
+workspace-pipeline compat claude --apply --preview "C:\absolute\compat-preview.json"
+```
+
+After a killed installer, a recorded dead-process lock can be recovered:
+
+```powershell
+workspace-pipeline compat claude recover-lock --json > lock-preview.json
+workspace-pipeline compat claude recover-lock --apply --preview "C:\absolute\lock-preview.json"
+```
+
+Recovery verifies the saved lock, current config hash and that the owner PID is
+not alive. It removes only that installer lock; it does not restore config or
+delete evidence. Then inspect backups and run fresh repair. A malformed lock,
+PID reuse, or a crash during lock recovery itself requires manual diagnosis;
+the tool refuses to guess or automatically delete an unknown/live lock.
+
+## Update and removal
+
+When a still-selected bundle drops its old native Grok member, ordinary update
+retires only owned Grok files/fields and preserves personal settings. Modified
+owned files remain conflicts; review/reset them explicitly. Codex delivery is
+not removed. Grok can also discover `.agents/skills`, so use matching canonical
+pipeline skills and check actual source selection, not merely unique names.
+
+Removing a workspace **leaves the user-wide compat preferences enabled**: other
+workspaces may depend on them. Backups are not restored automatically. To undo
+a preference, review the backup and current config and change only the relevant
+fields; never overwrite a later personal config wholesale with an old backup.
+
+## Contributor boundaries
+
+`src/compat/claude.js` owns the bounded profile editor/backup/lock and sanitized
+native inspection. `src/compat/lifecycle.js` binds the additional approval at
+the public CLI boundary; workspace schemas, historical recovery bytes and path
+ownership remain unchanged. Embedded `runCli` callers explicitly inject the
+compatibility service; the real executable supplies it. Source packages cannot
+provide executable adapter code or arbitrary global destinations.
+
+Run `node --test test/claude-compat.test.js`, the full regression and
+`npm run test:packed:claude-compat`. The packed test uses only temporary profiles
+and exercises a dual-provider-to-Claude-only migration, drift, repair/reset and
+removal. Neither a successful test nor this document claims publication or a
+real-workspace migration.

package/docs/doctor.md

@@ -5,7 +5,8 @@ The public CLI exposes it read-only:
 
 `workspace-pipeline doctor --workspace <absolute-path> [--recovery <relative-record>] [--json]`
 
-Output is JSON even without --json. Exit 0 means configuration ready, 1 not ready
+Output is a readable status summary by default. `--json` returns the complete
+machine report (including every target/hash). Exit 0 means configuration ready, 1 not ready
 or incomplete, 2 invalid invocation or output failure. This is not an install command.
 
 `ready` means observed **configuration readiness**, never a running harness,
@@ -110,8 +111,9 @@ This is installation metadata, not a pipeline/document version requirement.
   locks, renews approvals or silently selects an updated pipeline version.
 - A missing state is `not-installed` only when metadata is absent; residual
   metadata with no valid state remains incomplete, not a clean installation.
-- Provider-specific discovery/global compatibility checks are later adapter work;
-  synthetic provider-double readiness is not live-provider certification.
+- The public CLI additionally checks the [Claude-only Grok prerequisite](claude-grok.md),
+  including native compatibility inventory when an executable is available.
+  Synthetic provider-double readiness is not live-provider certification.
 
 ### Repository completion is not lock recovery
 

package/docs/launch.md

@@ -1,5 +1,23 @@
 # Scoped Grok launch (S11 development)
 
+For new Claude-only delivery, use **plain `grok`**, not this legacy launcher.
+See [Claude/Grok shared delivery](claude-grok.md). The launcher below is retained
+only for old native-Grok installations and deliberately sets imports false.
+
+## Configuration limitation (checked 2026-09-23)
+
+The desired UX is ordinary `grok` with workspace-local compatibility settings,
+not a mandatory launcher. This is currently blocked by the harness: installed
+Grok 1.0.40 and the upstream configuration reference list only `mcp_servers`,
+`plugins`, `permission`, and `mcp.max_output_bytes` as project config inputs.
+`compat.claude` is not among them. Writing five false values locally must not be
+represented as working import suppression. This legacy native-Grok route does
+not enable the new user-wide Claude compatibility prerequisite. It remains an
+explicit workaround, not the approved long-term configuration model.
+
+Source: [Grok configuration reference](https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-pager/docs/user-guide/26-config-reference.md),
+configuration layers and `compat` fields. No new live-isolation claim is made.
+
 This command starts Grok from an already configured workspace with five Claude
 compatibility switches set to false in the child environment: skills, rules, agents,
 MCP and hooks. It does not install a pipeline. Configure Grok using the ordinary

package/docs/lifecycle-cli.md

@@ -23,7 +23,8 @@ workspace-pipeline setup --workspace <absolute-wrapper> --apply --preview <absol
 workspace-pipeline update --workspace <absolute-wrapper> --apply --preview <absolute-json-file>
 ```
 
-Preview returns the complete prepared JSON on stdout. It may acquire a Git
+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
 is omitted, setup uses the standard workspace manifest; update uses the recorded
@@ -68,7 +69,7 @@ restoration; empty reset must be explicitly selected.
 
 ## Output and failures
 
-- stdout: one prepared JSON or operation result.
+- stdout: readable result by default; with `--json`, one complete prepared JSON or operation result.
 - stderr during apply: structured journal/recovery locations and operation events.
 - exit 0: preview created, or observed configuration ready with successful lock
   release and reporting. It never certifies harness/MCP runtime.
@@ -79,7 +80,10 @@ restoration; empty reset must be explicitly selected.
 If stdout fails after a successful apply, exit 2 does not undo that apply.
 Operation events and `doctor` distinguish actual configuration state from output
 delivery. Errors expose stable codes, not raw exception messages or argv secrets.
-No force unlock, rollback, retry or global configuration mutation is performed.
+The workspace transaction does not force unlock, rollback or mutate global config.
+For Claude-only delivery, the public CLI binds a separate, explicit
+[user-wide Grok prerequisite](claude-grok.md) to preview/apply. Workspace success
+followed by prerequisite failure is reported as `needs-compatibility`.
 
 ## Offline repair and removal
 
@@ -162,4 +166,7 @@ boundary, `uncertain: null` means no ambiguous write: only unrecorded operations
 and phase checks remain. Completed outcomes are not replayed. After both recorded
 phase checks, an empty remainder permits separately checked activation, not an
 inferred phase success. Failed/corrupt journals and changed targets fail closed.
-No source download, global setting change, force unlock or retention cleanup occurs.
+No source download, force unlock or retention cleanup occurs. A Claude-only
+continuation with an explicit compatibility envelope can apply its separately
+approved global prerequisite. Historical switch continuations only inspect it
+after activation; missing compatibility requires a fresh repair preview/apply.

package/docs/native-provider-format.md

@@ -127,6 +127,9 @@ owned routes therefore does not prove that harness can no longer discover a
 pipeline still installed for another provider. Installer ownership isolation and
 native discovery are distinct checks.
 
+The following describes legacy native-Grok delivery, not the new
+[Claude-only compatibility mode](claude-grok.md), which installs no Grok copies.
+
 Grok's child-environment helper sets five Claude compatibility switches to false:
 skills, rules, agents, MCP and hooks. It changes only the child environment,
 including removal of conflicting Windows key spellings. It does not switch

package/docs/rebind.md

@@ -15,8 +15,8 @@ The following PowerShell example uses illustrative absolute paths; replace them.
 Use a private directory for preview files: they can contain configuration values.
 
 ```powershell
-workspace-pipeline rebind --workspace 'C:\Work\Game' --manifest 'C:\Work\Game\workspace.json' > 'C:\Private\rebind.json'
-workspace-pipeline update --workspace 'C:\Work\Game' --accept-rebind 'C:\Private\rebind.json' > 'C:\Private\update.json'
+workspace-pipeline rebind --workspace 'C:\Work\Game' --manifest 'C:\Work\Game\workspace.json' --json > 'C:\Private\rebind.json'
+workspace-pipeline update --workspace 'C:\Work\Game' --accept-rebind 'C:\Private\rebind.json' --json > 'C:\Private\update.json'
 workspace-pipeline update --workspace 'C:\Work\Game' --apply --preview 'C:\Private\update.json'
 workspace-pipeline doctor --workspace 'C:\Work\Game'
 ```

package/docs/repositories.md

@@ -27,7 +27,7 @@ commit, not uncommitted files of its source.
 workspace-pipeline wrap --workspace "C:\Work\GameWorkspace" --manifest "C:\Work\workspace.json" --choices "C:\Work\choices.json"
 ```
 
-Save the exact JSON stdout as UTF-8 `preview.json` outside the affected repository
+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

package/docs/repository-recovery.md

@@ -39,8 +39,8 @@ delete pending markers or lock directories to make `doctor` report success.
 
 `no-pending-marker` means exactly that; it does not certify historical completion,
 provider readiness or game runtime. A blocker means further recovery is needed;
-this command never grants itself authority to resolve it. `--json` is redundant
-but accepted because JSON is already the default output.
+this command never grants itself authority to resolve it. Add `--json` for
+machine-readable output and whenever saving a preview for apply.
 
 ## Local recovery ownership
 

package/docs/reset.md

@@ -13,7 +13,7 @@ Close running harnesses/configuration editors. Keep preview files private: they
 contain before/after bytes, potentially including MCP credentials.
 
 ```powershell
-workspace-pipeline reset --workspace 'C:\Work\Game' --all > 'C:\Private\reset.json'
+workspace-pipeline reset --workspace 'C:\Work\Game' --all --json > 'C:\Private\reset.json'
 # Check $LASTEXITCODE and review reset.scope, reset.backup and preview.plan.targets.
 workspace-pipeline reset --workspace 'C:\Work\Game' --apply --preview 'C:\Private\reset.json'
 workspace-pipeline doctor --workspace 'C:\Work\Game'
@@ -55,7 +55,10 @@ Non-control table entries under `[agents]` are treated as named agent definition
 Unknown files outside the listed trees are not guessed to be pipeline files.
 Files under listed trees are included regardless of ignore rules. Empty directories
 and empty containing configuration files may remain; they are not an active skill
-or MCP declaration. Grok still uses its scoped launcher for import suppression.
+or MCP declaration. Legacy native Grok uses its scoped launcher; new Claude-only
+delivery uses [plain Grok and a separate compatibility prerequisite](claude-grok.md).
+Reset-to-installed may explicitly reapply that prerequisite; reset-to-empty and
+removal never disable user-wide compatibility.
 
 Malformed configurations, unsupported TOML representations, unsafe paths/links,
 hardlinks, repository overlap, unavailable snapshots, incompatible renderer replay,

package/docs/retention.md

@@ -75,7 +75,8 @@ check has cost proportional to selected files times retained records, bounded by
 scan limits and the user deletion cap. It is not a linear-cost guarantee or an
 OS-wide defense against hostile concurrent filesystem writers.
 
-Progress is emitted as JSON on stderr; final JSON is on stdout. The receipt path
+With `--json`, progress is emitted as JSON on stderr and final JSON on stdout;
+otherwise both are formatted for reading. Save apply previews using `--json`. The receipt path
 is under `.pipeline/cleanup/<run-id>.json`. Receipts record selected file hashes,
 confirmed deletions, reclaimed bytes, current intent and failures. These receipts
 describe attempted/deleted paths; unlike operational recovery records, they are

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@6reduk/workspace-pipeline",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Workspace-local Git pipeline configuration dispatcher",
   "type": "module",
   "bin": {
@@ -26,6 +26,7 @@
     "test:packed": "node scripts/verify-packed-cli.mjs",
     "test:packed:identity": "node scripts/verify-packed-identity.mjs",
     "test:packed:providers": "node scripts/verify-packed-providers.mjs",
+    "test:packed:claude-compat": "node scripts/verify-packed-claude-compat.mjs",
     "test:packed:pilot": "node scripts/verify-packed-pilot.mjs"
   },
   "dependencies": {

package/src/cli.js

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
 import {runCli} from './commands/dispatch.js';
 import {providerRegistry} from './providers/registry.js';
+import {outputWriter} from './commands/output.js';
+import {createClaudeCompatibility} from './compat/claude.js';
 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.
 process.stdout.on('error',()=>{});process.stderr.on('error',()=>{});
-process.exitCode=await runCli(process.argv.slice(2),{stdout:write(process.stdout),stderr:write(process.stderr),registry:providerRegistry});
+const args=process.argv.slice(2),json=args.includes('--json');
+process.exitCode=await runCli(args,{stdout:outputWriter(write(process.stdout),json),stderr:outputWriter(write(process.stderr),json),registry:providerRegistry,compatibility:createClaudeCompatibility()});

package/src/commands/compat.js

@@ -0,0 +1,22 @@
+import {fail} from '../contracts/parse.js';
+import {absoluteRoot} from '../workspace/paths.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {readRecord} from '../operations/state.js';
+export function parseCompat(args){
+  if(args[1]!=='claude')fail('cli.arguments');
+  const result={command:'compat',recover:args[2]==='recover-lock'},seen=new Set();
+  for(let i=result.recover?3:2;i<args.length;i++){
+    const flag=args[i];if(!['--json','--apply','--preview'].includes(flag)||seen.has(flag))fail('cli.arguments');seen.add(flag);
+    if(flag==='--json')continue;if(flag==='--apply'){result.apply=true;continue;}
+    const value=args[++i];if(!value||value.startsWith('--'))fail('cli.arguments');result.previewFile=absoluteRoot(value);
+  }
+  if(Boolean(result.apply)!==Boolean(result.previewFile))fail('cli.arguments');return result;
+}
+export async function runCompat(command,service,stdout){
+  if(!service)fail('grok-compat.unavailable');
+  if(!command.apply){const body={kind:'grok-compat-command',action:command.recover?'recover-lock':'enable',plan:await (command.recover?service.recovery():service.inspect())};
+    await stdout(JSON.stringify({...body,digest:contractDigest(body)})+'\n');return body.plan.status==='blocked'?1:0;}
+  const record=(await readRecord(command.previewFile)).value,{digest,...body}=record;
+  if(Object.keys(record).sort().join(',')!=='action,digest,kind,plan'||record.kind!=='grok-compat-command'||record.action!==(command.recover?'recover-lock':'enable')||digest!==contractDigest(body))fail('grok-compat.envelope');
+  const result=await (command.recover?service.recover(record.plan):service.apply(record.plan));await stdout(JSON.stringify(result)+'\n');return 0;
+}

package/src/commands/dispatch.js

@@ -26,9 +26,12 @@ import {parseMigrationCommand,runMigrationCommand} from './migration.js';
 import {parseLaunch,runLaunch} from './launch.js';
 import {parseRebind,runRebind,acceptedRebind} from './rebind.js';
 import {parseReset,runReset} from './reset.js';
+import {bindCompatibility,unwrapCompatibility,finishCompatibility,doctorCompatibility} from '../compat/lifecycle.js';
+import {parseCompat,runCompat} from './compat.js';
 
 export const help=`Workspace Pipeline CLI — development preview
 Usage: workspace-pipeline doctor --workspace <absolute-directory> [--recovery <relative-record>] [--json]
+       workspace-pipeline compat claude [recover-lock] [--apply --preview <absolute-json-file>] [--json]
        workspace-pipeline launch grok --workspace <absolute-directory> --executable <absolute-native-executable> [--inspect] [--execute]
        workspace-pipeline <init|adopt|wrap> --workspace <absolute-directory> --choices <absolute-json-file> [--manifest <absolute-file>] [--network]
        workspace-pipeline <init|adopt|wrap> --workspace <absolute-directory> --apply --preview <absolute-json-file>
@@ -62,7 +65,9 @@ Preview stages Git externally; inspect is read-only/offline. JSON can contain
 private config bytes. Only explicit apply writes or clears a validated pending marker.
 Apply requires the saved installer-bound envelope and accepts no source overrides.
 
-Doctor is read-only and prints JSON. Exit 0 means observed configuration ready;
+Output is human-readable by default; use --json for complete machine output.
+Save previews for apply with --json (including when redirecting stdout).
+Doctor is read-only. Exit 0 means observed configuration ready;
 exit 1 means not ready/incomplete; exit 2 means invalid invocation or unavailable command.
 Runtime, MCP/harness discovery and provider compatibility are NOT verified.
 No source access, automatic repair or lock removal. Read-only/configuration commands never clean history.
@@ -134,15 +139,16 @@ logs clean --repositories --workspace <absolute-directory> --max-age-days <N>
 Apply with --repositories --apply --preview <file>; this is a separate cleanup
 domain, never an implicit increase of the ordinary journal deletion budget.
 Execution inputs are retained privately under .pipeline/repository-inputs;
---json is optional because JSON is the default.
+--json selects the complete machine-readable result without presentation changes.
 This package is not ready to replace an existing installation.`;
 
 // Parse strictly before any filesystem observation. Never echo unknown arguments
 // (which can contain credentials). Output transport is trusted CLI code.
 export function parseCommand(args) {
   if(!Array.isArray(args) || args.some(a=>typeof a!=='string')) fail('cli.arguments');
-  if(args.length===0 || (args.length===1 && ['--help','-h'].includes(args[0])))return {command:'help'};
+  if(args.length===0 || (['--help','-h'].includes(args[0]) && (args.length===1 || (args.length===2 && args[1]==='--json'))))return {command:'help'};
   if(args[0]==='launch')return parseLaunch(args);
+  if(args[0]==='compat')return parseCompat(args);
   if(args[0]==='rebind')return parseRebind(args);
   if(args[0]==='reset')return parseReset(args);
   if(['setup','update','repair','remove','switch','continue'].includes(args[0]))return parseLifecycle(args);
@@ -259,7 +265,7 @@ function parseLifecycle(args) {
   return result;
 }
 
-async function runLifecycle(command,registry,stdout,stderr) {
+async function runLifecycle(command,registry,stdout,stderr,compatibility) {
   // A trusted embedding/CLI assembly can supply functions; argv and package
   // data cannot. Until real adapters ship, the default command fails before IO.
   if(registry===null || registry===undefined)fail('cli.providers-unavailable');
@@ -275,12 +281,22 @@ async function runLifecycle(command,registry,stdout,stderr) {
     if(command.bundles)input.bundles=command.bundles;
     if(command.recoveryPath)input.recoveryPath=command.recoveryPath;
     if(command.rebindFile)Object.assign(input,await acceptedRebind(command.workspace,command.rebindFile));
-    await stdout(JSON.stringify(await prepare(input,registry))+'\n');return 0;
+    const prepared=await prepare(input,registry);
+    await stdout(JSON.stringify(command.command==='remove'?prepared:await bindCompatibility(prepared,compatibility))+'\n');return 0;
   }
-  const prepared=(await readRecord(command.previewFile)).value;
-  const result=await apply({command:command.command,wrapper:command.workspace,prepared,
+  const saved=(await readRecord(command.previewFile)).value;
+  const unwrapped=command.command==='remove'?{prepared:saved,compatibility:null}:await unwrapCompatibility(saved,compatibility);
+  const prepared=unwrapped.prepared;
+  const workspaceResult=await apply({command:command.command,wrapper:command.workspace,prepared,
     approval:{decision:'approve',preparedDigest:prepared.digest}},registry,
     {report:async event=>stderr(JSON.stringify(event)+'\n')});
+  let result=await finishCompatibility(workspaceResult,unwrapped.compatibility,compatibility);
+  // Historical switch continuations do not carry a desired-provider envelope.
+  // Inspect the activated installation, but never infer approval for a global write.
+  if(command.command==='continue'&&!unwrapped.compatibility&&compatibility&&result.status==='ready'&&result.lockRelease==='released'){
+    const checked=await doctorCompatibility(await inspectInstallation(command.workspace),compatibility);
+    if(checked.compatibility)result={...result,compatibility:checked.compatibility,...checked.status==='needs-compatibility'?{workspaceStatus:'ready',status:'needs-compatibility'}:{}};
+  }
   await stdout(JSON.stringify(result)+'\n');
   return (result.status==='ready' || (['remove','continue'].includes(command.command) && result.status==='not-installed')) && result.lockRelease==='released' && !result.outputError?0:1;
 }
@@ -384,14 +400,15 @@ async function runLogs(command,stdout,stderr) {
   }finally{await lock.release();}
 }
 
-export async function runCli(args,{stdout,stderr,registry=null}) {
+export async function runCli(args,{stdout,stderr,registry=null,compatibility=null}) {
   if(typeof stdout!=='function' || typeof stderr!=='function')fail('cli.transport');
   try {
     const command=parseCommand(args);
     if(command.command==='help') {await stdout(help+'\n');return 0;}
+    if(command.command==='compat')return await runCompat(command,compatibility,stdout);
     if(command.command==='launch')return await runLaunch(command,stdout,stderr);
     if(command.command==='rebind')return await runRebind(command,stdout);
-    if(command.command==='reset')return await runReset(command,registry,stdout,stderr);
+    if(command.command==='reset')return await runReset(command,registry,stdout,stderr,compatibility);
     if(command.command==='migration')return await runMigrationCommand(command,stdout,stderr);
     if(command.command==='logs')return await runLogs(command,stdout,stderr);
     if(command.command==='policy')return await runPolicy(command,stdout);
@@ -400,9 +417,9 @@ export async function runCli(args,{stdout,stderr,registry=null}) {
       ['abandon','continue-abandon'].includes(command.action)?runRepositoryAbandon:
       command.action==='recover-locks'?runRepositoryLockRecovery:
       ['recover-bootstrap','continue-bootstrap','retire-bootstrap'].includes(command.action)?runBootstrapContinuation:runRepositoryRecovery)(command,stdout);
-    if(['setup','update','repair','remove','switch','continue'].includes(command.command))return await runLifecycle(command,registry,stdout,stderr);
+    if(['setup','update','repair','remove','switch','continue'].includes(command.command))return await runLifecycle(command,registry,stdout,stderr,compatibility);
     const options=command.recoveryPath===undefined?{}:{recoveryPath:command.recoveryPath};
-    const result=await inspectInstallation(command.workspace,options);
+    const result=await doctorCompatibility(await inspectInstallation(command.workspace,options),compatibility);
     await stdout(JSON.stringify(result)+'\n');
     return result.ready?0:1;
   } catch(error) {

package/src/commands/launch.js

@@ -11,8 +11,9 @@ export function parseLaunch(args) {
   const result = { command: 'launch', provider: 'grok', execute: false, inspect: false }, seen = new Set();
   for (let i = 2; i < args.length; i++) {
     const flag = args[i];
-    if (!['--workspace', '--executable', '--execute', '--inspect'].includes(flag) || seen.has(flag)) fail('cli.arguments');
+    if (!['--workspace', '--executable', '--execute', '--inspect', '--json'].includes(flag) || seen.has(flag)) fail('cli.arguments');
     seen.add(flag);
+    if (flag === '--json') continue;
     if (flag === '--execute') { result.execute = true; continue; }
     if (flag === '--inspect') { result.inspect = true; continue; }
     const value = args[++i];

package/src/commands/output.js

@@ -0,0 +1,51 @@
+// Presentation boundary only: internal command results and saved JSON contracts
+// remain unchanged. Never infer success from the shape of a rendered result.
+const safe = value => String(value).replace(/[\u0000-\u001f\u007f-\u009f]/g, c => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+const privateKey = /bytes|base64|content|secret|token|password/i;
+
+export function formatResult(value) {
+  if (value && typeof value.ready === 'boolean' && Array.isArray(value.diagnostics)) {
+    const lines = ['Workspace Pipeline — doctor', '',
+      `Workspace: ${safe(value.workspace ?? '(not reported)')}`,
+      `Status: ${value.ready ? 'READY' : 'NOT READY'} (${safe(value.status ?? 'unknown')})`];
+    if (value.pipeline) lines.push(`Pipeline: ${safe(value.pipeline.id)} @ ${safe(value.pipeline.version)}`,
+      `Providers: ${value.pipeline.providers.map(safe).join(', ')}`);
+    for (const key of ['configuration', 'transactionEvidence']) if (value[key] !== undefined) lines.push(`${key}: ${safe(value[key])}`);
+    if(value.compatibility)lines.push(`Grok / Claude compatibility: ${safe(value.compatibility.status)}`,
+      ...(value.compatibility.path?[`User config: ${safe(value.compatibility.path)}`]:[]),
+      ...(value.compatibility.blockers??[]).map(b=>`  - ${safe(b)}`),
+      `Native compatibility inspection: ${safe(value.compatibility.native?.status??'not-run')}.`,
+      'Native discovery is not model/agent/MCP execution certification.');
+    lines.push('', `Diagnostics: ${value.diagnostics.length}`);
+    for (const item of value.diagnostics) lines.push(`  - ${safe(item.code)}${item.subject ? ': ' + safe(item.subject) : ''}${item.pointer ? ' ' + safe(item.pointer) : ''}`);
+    lines.push('', 'Runtime / model-visible skills / MCP: not verified by doctor.',
+      'Full report: repeat with --json.');
+    return lines.join('\n') + '\n';
+  }
+  const lines = ['Workspace Pipeline', ''];
+  function render(node, indent = '', depth = 0) {
+    if (node === null || typeof node !== 'object') { lines.push(indent + safe(node)); return; }
+    if (depth > 5) { lines.push(indent + '(details omitted; use --json)'); return; }
+    const entries = Object.entries(node);
+    for (const [key, item] of entries.slice(0, 40)) {
+      const label = indent + safe(key) + ':';
+      if (privateKey.test(key)) lines.push(label + ' (private payload; use --json)');
+      else if (item !== null && typeof item === 'object') { lines.push(label); render(item, indent + '  ', depth + 1); }
+      else { const text=safe(item); lines.push(label + ' ' + (text.length>500?text.slice(0,500)+' (truncated; use --json)':text)); }
+    }
+    if (entries.length > 40) lines.push(indent + `(${entries.length - 40} more entries; use --json)`);
+  }
+  render(value);
+  lines.push('', 'For complete machine output or a saved apply preview, repeat with --json.',
+    'This display is not an apply preview. JSON may contain private configuration.');
+  return lines.join('\n') + '\n';
+}
+
+export function outputWriter(write, json) {
+  if (json) return write;
+  return text => {
+    let value;
+    try { value = JSON.parse(text); } catch { return write(text); }
+    return write(formatResult(value));
+  };
+}

package/src/commands/rebind.js

@@ -9,8 +9,9 @@ export function parseRebind(args) {
   const result={command:'rebind'},seen=new Set();
   for(let i=1;i<args.length;i++) {
     const flag=args[i];
-    if(!['--workspace','--manifest'].includes(flag) || seen.has(flag))fail('cli.arguments');
+    if(!['--workspace','--manifest','--json'].includes(flag) || seen.has(flag))fail('cli.arguments');
     seen.add(flag);
+    if(flag==='--json')continue;
     const value=args[++i];if(!value || value.startsWith('--'))fail('cli.arguments');
     result[flag==='--workspace'?'workspace':'manifestPath']=absoluteRoot(value);
   }

package/src/commands/reset.js

@@ -6,13 +6,15 @@ import {applyReset} from '../operations/apply.js';
 import {acquireWorkspaceLock} from '../operations/lock.js';
 import {inspectHistory} from '../operations/history.js';
 import {assertNoRepositoryPending} from '../operations/repository-pending.js';
+import {bindCompatibility,unwrapCompatibility,finishCompatibility} from '../compat/lifecycle.js';
 
 export function parseReset(args){
   const result={command:'reset'},seen=new Set();
   for(let i=1;i<args.length;i++){
     const flag=args[i];
-    if(!['--workspace','--to','--all','--providers','--bundles','--apply','--preview'].includes(flag) || seen.has(flag))fail('cli.arguments');
+    if(!['--workspace','--to','--all','--providers','--bundles','--apply','--preview','--json'].includes(flag) || seen.has(flag))fail('cli.arguments');
     seen.add(flag);
+    if(flag==='--json')continue;
     if(flag==='--apply'){result.apply=true;continue;}
     if(flag==='--all'){(result.options??={}).all=true;continue;}
     const value=args[++i];if(!value || value.startsWith('--'))fail('cli.arguments');
@@ -34,12 +36,13 @@ async function history(workspace){
   await assertNoRepositoryPending(workspace);
   const h=await inspectHistory(workspace);if(!h.complete || h.diagnostics.length)fail('reset.history');
 }
-export async function runReset(command,registry,stdout,stderr){
+export async function runReset(command,registry,stdout,stderr,compatibility=null){
   if(!command.apply){
     await history(command.workspace);
-    await stdout(JSON.stringify(await prepareReset(command.workspace,registry,command.options))+'\n');return 0;
+    await stdout(JSON.stringify(await bindCompatibility(await prepareReset(command.workspace,registry,command.options),compatibility))+'\n');return 0;
   }
-  const raw=(await readRecord(command.previewFile)).value;
+  const unwrapped=await unwrapCompatibility((await readRecord(command.previewFile)).value,compatibility);
+  const raw=unwrapped.prepared;
   const approval={decision:'approve',preparedDigest:raw.digest};
   const prepared=validateResetRecord(raw,approval);
   if(prepared.preview.plan.workspace!==command.workspace)fail('reset.workspace');
@@ -58,6 +61,7 @@ export async function runReset(command,registry,stdout,stderr){
     result.status=applied.status;
   }catch(error){result.error=error instanceof ContractError?error.code:'reset.io';}
   finally{if(lock)try{await lock.release();result.lockRelease='released';}catch{result.lockRelease='failed';}}
-  await stdout(JSON.stringify(result)+'\n');
-  return ['ready','not-installed'].includes(result.status) && result.lockRelease==='released'?0:1;
+  const final=await finishCompatibility(result,unwrapped.compatibility,compatibility);
+  await stdout(JSON.stringify(final)+'\n');
+  return ['ready','not-installed'].includes(final.status) && final.lockRelease==='released'?0:1;
 }

package/src/compat/claude.js

@@ -0,0 +1,152 @@
+// Compiled user-profile policy, outside workspace ownership. Packages cannot
+// choose global paths or arbitrary keys. No harness, model or MCP is launched.
+import path from 'node:path';
+import {homedir} from 'node:os';
+import {lstat,readFile,mkdir,rename,unlink,open} from 'node:fs/promises';
+import {randomUUID} from 'node:crypto';
+import {isDeepStrictEqual} from 'node:util';
+import {promisify} from 'node:util';
+import {execFile} from 'node:child_process';
+import {parseTOML,getStaticTOMLValue} from 'toml-eslint-parser';
+import {fail} from '../contracts/parse.js';
+import {contractDigest} from '../contracts/semantic.js';
+import {sha256,utf8} from '../source/inventory.js';
+export const compatKeys=Object.freeze(['skills','rules','agents','mcps','hooks']);
+const keys=node=>node.keys.map(k=>k.name??k.value);
+const object=v=>v!==null&&typeof v==='object'&&!Array.isArray(v)&&!(v instanceof Date);
+function document(bytes){
+  if(bytes!==null&&(!Buffer.isBuffer(bytes)||bytes.length>1024*1024))fail('grok-compat.size');
+  const text=bytes===null?'':utf8(bytes);
+  let ast,value;try{ast=parseTOML(text,{tomlVersion:'1.0'});value=getStaticTOMLValue(ast);}catch{fail('grok-compat.syntax');}
+  if(value.compat!==undefined&&!object(value.compat))fail('grok-compat.shape');
+  if(value.compat?.claude!==undefined&&!object(value.compat.claude))fail('grok-compat.shape');
+  if(value.claude_compat?.imported===true)fail('grok-compat.import-marker');
+  for(const k of compatKeys)if(value.compat?.claude?.[k]!==undefined&&typeof value.compat.claude[k]!=='boolean')fail('grok-compat.shape');
+  return {text,ast,value};
+}
+export function enableClaudeCompat(bytes){
+  const {text,ast,value}=document(bytes),edits=[],seen=new Set();
+  const changes=compatKeys.filter(k=>value.compat?.claude?.[k]!==true);
+  if(!changes.length)return {bytes:bytes??Buffer.alloc(0),changes};
+  let table=null,parentTable=null;
+  function pair(node,base){
+    const p=[...base,...keys(node.key)];if(p[0]!=='compat')return;
+    if(p.length===1||(p.length===2&&p[1]==='claude'))fail('grok-compat.inline-ancestor');
+    if(p.length===3&&p[1]==='claude'&&compatKeys.includes(p[2])){
+      seen.add(p[2]);if(changes.includes(p[2]))edits.push([...node.value.range,'true']);
+    }
+  }
+  for(const node of ast.body[0].body){
+    if(node.type==='TOMLKeyValue')pair(node,[]);
+    else if(node.type==='TOMLTable'){
+      if(node.resolvedKey.join('.')==='compat.claude'){if(node.kind!=='standard')fail('grok-compat.shape');table=node;}
+      if(node.resolvedKey.length===1&&node.resolvedKey[0]==='compat'){if(node.kind!=='standard')fail('grok-compat.shape');parentTable=node;}
+      for(const item of node.body)pair(item,node.resolvedKey);
+    }
+  }
+  const missing=compatKeys.filter(k=>!seen.has(k)),nl=text.includes('\r\n')?'\r\n':'\n';
+  if(missing.length){
+    const selected=table??parentTable;
+    if(selected){const end=text.indexOf('\n',selected.key.range[1]),pos=end<0?text.length:end+1;
+      edits.push([pos,pos,(end<0?nl:'')+missing.map(k=>`${table?'':'claude.'}${k} = true${nl}`).join('')]);
+    }else edits.push([0,0,missing.map(k=>`compat.claude.${k} = true${nl}`).join('')]);
+  }
+  let result=text;for(const [start,end,replacement]of edits.sort((a,b)=>b[0]-a[0]))result=result.slice(0,start)+replacement+result.slice(end);
+  const expected=structuredClone(value);expected.compat??={};expected.compat.claude??={};for(const k of compatKeys)expected.compat.claude[k]=true;
+  // The strict decoder consumes a leading UTF-8 BOM; preserve it on re-encode.
+  const bom=bytes?.subarray(0,3).equals(Buffer.from([0xef,0xbb,0xbf]));
+  const output=Buffer.from((bom?'\uFEFF':'')+result);if(!isDeepStrictEqual(document(output).value,expected))fail('grok-compat.postcondition');
+  return {bytes:output,changes};
+}
+async function stat(p){try{return await lstat(p);}catch(e){if(e.code==='ENOENT')return null;throw e;}}
+async function safe(p){
+  let current=path.parse(p).root;
+  for(const segment of path.relative(current,p).split(path.sep)){
+    current=path.join(current,segment);const s=await stat(current);
+    if(s&&(s.isSymbolicLink()||(!s.isDirectory()&&current!==p)))fail('grok-compat.path');
+  }
+}
+async function read(p){
+  await safe(p);const s=await stat(p);if(!s)return null;
+  if(!s.isFile()||s.nlink!==1||s.size>1024*1024)fail('grok-compat.file');
+  const bytes=await readFile(p),after=await lstat(p);
+  if(after.ino!==s.ino||after.dev!==s.dev||after.size!==bytes.length||after.mtimeMs!==s.mtimeMs)fail('grok-compat.drift');
+  return bytes;
+}
+const digest=b=>b===null?null:sha256(b);
+async function record(p,value){const h=await open(p,'wx',0o600);try{await h.writeFile(JSON.stringify(value,null,2)+'\n');await h.sync();}finally{await h.close();}}
+const warning='User-wide Claude compatibility affects every Grok workspace, including user hooks/MCP. Removing one workspace does not disable it.';
+export function createClaudeCompatibility({env=process.env,home=homedir()}={}){
+  function profile(){const base=env.GROK_HOME||path.join(env.USERPROFILE||env.HOME||home,'.grok');if(!path.isAbsolute(base))fail('grok-compat.home');return path.resolve(base);}
+  async function executable(){
+    const filename=process.platform==='win32'?'grok.exe':'grok';
+    const candidates=[path.join(env.USERPROFILE||env.HOME||home,'.grok','bin',filename),...(env.PATH||'').split(path.delimiter).filter(p=>path.isAbsolute(p)).map(p=>path.join(p,filename))];
+    for(const p of candidates)if((await stat(p))?.isFile())return p;return null;
+  }
+  async function inspect(){
+    const base=profile(),target=path.join(base,'config.toml');await safe(base);
+    if(!await stat(base)&&!await executable())return {kind:'grok-claude-prerequisite',profile:base,path:target,status:'not-present',beforeHash:null,resultHash:null,changes:[],blockers:[],warning};
+    const before=await read(target),edited=enableClaudeCompat(before),blockers=[];
+    for(const key of compatKeys){const name=`GROK_CLAUDE_${key.toUpperCase()}_ENABLED`;if(Object.keys(env).some(k=>k.toUpperCase()===name&&!['1','true'].includes(String(env[k]).toLowerCase())))blockers.push('environment:'+name);}
+    for(const name of ['managed_config.toml','requirements.toml'])if(await stat(path.join(base,name)))blockers.push('policy:'+name);
+    if(await stat(path.join(base,'workspace-pipeline-compat.lock')))blockers.push('global-lock');
+    if(await stat(path.join(base,'workspace-pipeline-compat-recovery.lock')))blockers.push('global-recovery-lock');
+    return {kind:'grok-claude-prerequisite',profile:base,path:target,status:blockers.length?'blocked':edited.changes.length?'needs-apply':'configured',beforeHash:digest(before),resultHash:digest(edited.bytes),changes:edited.changes,blockers,warning,verification:'config-only; native effective state and runtime not verified'};
+  }
+  async function check(expected){const actual=await inspect();if(contractDigest(actual)!==contractDigest(expected))fail('grok-compat.preview-drift');if(actual.status==='blocked')fail('grok-compat.blocked');return actual;}
+  async function apply(expected){
+    const plan=await check(expected);if(plan.status!=='needs-apply')return {...plan,changed:false};
+    const base=profile(),lockPath=path.join(base,'workspace-pipeline-compat.lock');await safe(base);await mkdir(base,{recursive:true,mode:0o700});await safe(base);
+    const token=randomUUID(),lock=await open(lockPath,'wx',0o600);let temporary,backupDir,lockBytes;
+    try{
+      lockBytes=Buffer.from(JSON.stringify({pid:process.pid,token,createdAt:new Date().toISOString()})+'\n');await lock.writeFile(lockBytes);await lock.sync();
+      if(await stat(path.join(base,'workspace-pipeline-compat-recovery.lock')))fail('grok-compat.recovery-active');
+      const before=await read(plan.path);if(digest(before)!==plan.beforeHash)fail('grok-compat.preview-drift');
+      const output=enableClaudeCompat(before).bytes;if(digest(output)!==plan.resultHash)fail('grok-compat.preview-drift');
+      backupDir=path.join(base,'workspace-pipeline-backups',token);await safe(backupDir);await mkdir(backupDir,{recursive:true,mode:0o700});
+      if(before!==null){const b=await open(path.join(backupDir,'config.before.toml'),'wx',0o600);try{await b.writeFile(before);await b.sync();}finally{await b.close();}}
+      if(before!==null&&digest(await read(path.join(backupDir,'config.before.toml')))!==plan.beforeHash)fail('grok-compat.backup');
+      await record(path.join(backupDir,'operation.json'),{schemaVersion:1,kind:'grok-claude-compatibility',plan,pid:process.pid,token,scope:compatKeys,restoration:'Explicit only; never overwrite later user edits'});
+      temporary=path.join(base,`workspace-pipeline-${token}.tmp`);const h=await open(temporary,'wx',0o600);try{await h.writeFile(output);await h.sync();}finally{await h.close();}
+      if(digest(await read(plan.path))!==plan.beforeHash)fail('grok-compat.preview-drift');await rename(temporary,plan.path);temporary=null;
+      if(digest(await read(plan.path))!==plan.resultHash)fail('grok-compat.readback');
+      await record(path.join(backupDir,'completed.json'),{resultHash:plan.resultHash});
+      return {...plan,status:'configured',changed:true,backupDir};
+    }finally{await lock.close();if(temporary)await unlink(temporary).catch(()=>{});if(lockBytes&&(await read(lockPath))?.equals(lockBytes))await unlink(lockPath);}
+  }
+  async function recovery(){
+    const base=profile(),lockPath=path.join(base,'workspace-pipeline-compat.lock'),bytes=await read(lockPath);
+    if(bytes===null)fail('grok-compat.no-lock');
+    let owner;try{owner=JSON.parse(utf8(bytes));}catch{fail('grok-compat.lock-record');}
+    if(Object.keys(owner).sort().join(',')!=='createdAt,pid,token'||!Number.isSafeInteger(owner.pid)||owner.pid<1||
+      !/^[a-f0-9-]{36}$/.test(owner.token)||typeof owner.createdAt!=='string')fail('grok-compat.lock-record');
+    try{process.kill(owner.pid,0);fail('grok-compat.owner-running');}catch(e){if(e.code!=='ESRCH')throw e;}
+    if(await stat(path.join(base,'workspace-pipeline-compat-recovery.lock')))fail('grok-compat.recovery-active');
+    return {kind:'grok-compat-lock-recovery',profile:base,path:lockPath,lockHash:sha256(bytes),owner,
+      configHash:digest(await read(path.join(base,'config.toml'))),backupDir:path.join(base,'workspace-pipeline-backups',owner.token),
+      warning:'Removes only this dead-process installer lock. Does not restore or rewrite config, backups or workspace.'};
+  }
+  async function recover(expected){
+    const actual=await recovery();if(contractDigest(actual)!==contractDigest(expected))fail('grok-compat.preview-drift');
+    const guardPath=path.join(profile(),'workspace-pipeline-compat-recovery.lock'),guard=await open(guardPath,'wx',0o600);
+    const guardBytes=Buffer.from(JSON.stringify({pid:process.pid,token:randomUUID()}));
+    try{
+      await guard.writeFile(guardBytes);await guard.sync();
+      const bytes=await read(actual.path);if(digest(bytes)!==actual.lockHash||digest(await read(path.join(profile(),'config.toml')))!==actual.configHash)fail('grok-compat.preview-drift');
+      try{process.kill(actual.owner.pid,0);fail('grok-compat.owner-running');}catch(e){if(e.code!=='ESRCH')throw e;}
+      await unlink(actual.path);return {...actual,status:'lock-released',next:'Run repair preview/apply; preserve backups and inspect whether the prior config write completed.'};
+    }finally{await guard.close();if((await read(guardPath))?.equals(guardBytes))await unlink(guardPath);}
+  }
+  async function verify(workspace){
+    const binary=await executable();if(!binary)return {status:'not-available',runtime:'not-run'};
+    if(!path.isAbsolute(workspace))fail('grok-compat.workspace');
+    try{
+      const {stdout}=await promisify(execFile)(binary,['inspect','--json'],{cwd:workspace,env,windowsHide:true,encoding:'utf8',timeout:30000,maxBuffer:8*1024*1024});
+      const data=JSON.parse(stdout),cells=data.externalCompat?.cells;
+      const effective=compatKeys.map(surface=>({surface,enabled:Array.isArray(cells)&&cells.filter(c=>c.vendor==='claude'&&c.surface===surface).length===1&&cells.find(c=>c.vendor==='claude'&&c.surface===surface).enabled===true}));
+      return {status:effective.every(c=>c.enabled)?'verified':'blocked',effective,projectTrusted:data.projectTrusted===true,
+        runtime:'not-run',method:'native inspect only; no trust grant, model or MCP invocation'};
+    }catch{return {status:'blocked',code:'grok-compat.native-inspect',runtime:'not-run'};}
+  }
+  return Object.freeze({inspect,check,apply,recovery,recover,verify});
+}

package/src/compat/lifecycle.js

@@ -0,0 +1,45 @@
+import {contractDigest} from '../contracts/semantic.js';
+import {fail,ContractError,parse} from '../contracts/parse.js';
+export const usesClaudeCompatibility=providers=>providers?.includes('claude')&&!providers.includes('grok');
+const selected=p=>usesClaudeCompatibility(p?.preview?.plan?.desired?.providers??
+  (p?.kind==='prepared-switch'?p.preview?.phases?.find(s=>s.name==='install-new')?.preview?.plan?.desired?.providers:undefined));
+export async function bindCompatibility(prepared,service){
+  if(!service||!selected(prepared))return prepared;
+  const body={kind:'prepared-with-claude-compatibility',workspace:prepared,compatibility:await service.inspect()};
+  const result={...body,digest:contractDigest(body)};
+  parse(JSON.stringify(result),'json'); // Still readable by the public preview reader.
+  return result;
+}
+export async function unwrapCompatibility(prepared,service){
+  if(prepared?.kind!=='prepared-with-claude-compatibility'){
+    if(service&&selected(prepared))fail('grok-compat.preview-required');
+    return {prepared,compatibility:null};
+  }
+  if(!service||Object.keys(prepared).sort().join(',')!=='compatibility,digest,kind,workspace'||!selected(prepared.workspace))fail('grok-compat.envelope');
+  const {digest,...body}=prepared;if(digest!==contractDigest(body))fail('grok-compat.envelope');
+  await service.check(prepared.compatibility);
+  return {prepared:prepared.workspace,compatibility:prepared.compatibility};
+}
+export async function finishCompatibility(result,requirement,service){
+  if(!requirement)return result;
+  if(result.status!=='ready'||result.lockRelease!=='released'||result.outputError)return {...result,compatibility:{status:'not-applied',reason:'workspace-operation-incomplete'}};
+  try{
+    const compatibility=await service.apply(requirement);
+    if(compatibility.status==='configured'&&service.verify&&result.workspace){
+      compatibility.native=await service.verify(result.workspace);
+      if(compatibility.native.status==='blocked')return {...result,workspaceStatus:result.status,status:'needs-compatibility',compatibility};
+    }
+    return {...result,compatibility};
+  }
+  catch(error){return {...result,workspaceStatus:result.status,status:'needs-compatibility',compatibility:{status:'failed',profile:requirement.profile,error:error instanceof ContractError?error.code:'grok-compat.io',next:'Run repair preview/apply; workspace changes are already committed. Inspect workspace-pipeline-backups and the global lock in this profile before retry after a process crash.'}};}
+}
+export async function doctorCompatibility(result,service){
+  if(!service||!usesClaudeCompatibility(result.pipeline?.providers))return result;
+  try{
+    const compatibility=await service.inspect();
+    if(compatibility.status==='configured'&&service.verify&&result.workspace)compatibility.native=await service.verify(result.workspace);
+    const okay=['configured','not-present'].includes(compatibility.status)&&compatibility.native?.status!=='blocked';
+    return {...result,compatibility,ready:result.ready&&okay,status:okay?result.status:'needs-compatibility',
+      diagnostics:[...result.diagnostics,...okay?[]:[{code:compatibility.native?.status==='blocked'?'grok-compat.native-mismatch':'grok-compat.'+compatibility.status,subject:compatibility.path}]]};
+  }catch(error){return {...result,ready:false,status:'needs-compatibility',compatibility:{status:'blocked'},diagnostics:[...result.diagnostics,{code:error instanceof ContractError?error.code:'grok-compat.io',subject:'Grok user profile'}]};}
+}