@6reduk/workspace-pipeline 0.4.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).

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

@@ -111,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,9 @@
 # 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,
@@ -7,8 +11,8 @@ 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. The CLI does not change user-wide
-compat settings as a substitute. The legacy launch route below remains an
+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),

package/docs/lifecycle-cli.md

@@ -80,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
 
@@ -163,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/reset.md

@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@6reduk/workspace-pipeline",
-  "version": "0.4.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

@@ -2,8 +2,9 @@
 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',()=>{});
 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});
+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>
@@ -145,6 +148,7 @@ export function parseCommand(args) {
   if(!Array.isArray(args) || args.some(a=>typeof a!=='string')) fail('cli.arguments');
   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);
@@ -261,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');
@@ -277,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;
 }
@@ -386,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);
@@ -402,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/output.js

@@ -11,6 +11,11 @@ export function formatResult(value) {
     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.',

package/src/commands/reset.js

@@ -6,6 +6,7 @@ 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();
@@ -35,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');
@@ -59,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'}]};}
+}