@thebackstoryis/engineering-with-ai 0.3.1-beta.0 → 0.3.2

package/src/config-document.mjs

@@ -0,0 +1,49 @@
+import {constants,openSync,closeSync,fstatSync,lstatSync,readFileSync,writeFileSync,renameSync,unlinkSync,realpathSync,fsyncSync,existsSync} from 'node:fs';
+import {dirname,relative,resolve,isAbsolute} from 'node:path';
+import {createHash,randomUUID} from 'node:crypto';
+import YAML from 'yaml';
+import {projectPaths} from './paths.mjs';
+
+function fail(message,statusCode=409){const error=new Error(message);error.statusCode=statusCode;error.configurationError=true;throw error;}
+function safePath(paths){
+  const root=realpathSync(paths.projectRoot),parent=dirname(paths.configPath),rel=relative(root,realpathSync(parent));
+  if(rel.startsWith('..')||isAbsolute(rel))fail('Settings require a safe project configuration path.',403);
+  let cursor=parent;
+  while(cursor!==paths.projectRoot){if(lstatSync(cursor).isSymbolicLink())fail('Settings cannot use a symbolic configuration directory.',403);const next=dirname(cursor);if(next===cursor)fail('Settings require a safe project configuration path.',403);cursor=next;}
+  const stat=lstatSync(paths.configPath);
+  if(!stat.isFile()||stat.isSymbolicLink()||stat.nlink!==1)fail('Settings require a regular, non-symbolic configuration file.',403);
+  if(stat.size>2*1024*1024)fail('The project configuration is too large for settings editing.',413);
+  return stat;
+}
+export function readProjectDocument(projectRoot){
+  const paths=projectPaths(projectRoot);let fd;
+  try{
+    const stat=safePath(paths);fd=openSync(paths.configPath,constants.O_RDONLY|constants.O_NOFOLLOW);
+    const opened=fstatSync(fd);if(opened.ino!==stat.ino||opened.dev!==stat.dev)fail('Project configuration changed. Reload the settings and try again.');
+    const bytes=readFileSync(fd);if(bytes.length>2*1024*1024)fail('The project configuration is too large for settings editing.',413);
+    const document=YAML.parseDocument(bytes.toString('utf8'));
+    if(document.errors.length)fail('Project configuration contains invalid YAML. Fix it before editing settings.',422);
+    let config;try{config=document.toJS({maxAliasCount:100});}catch{fail('The project configuration cannot be safely read.',422);}
+    if(config?.schema!=='ewai.project/v1'||config?.specs?.root!==paths.specsRelative)fail('Project configuration and SPECS locator must agree before editing settings.',422);
+    return {paths,document,config,digest:'sha256:'+createHash('sha256').update(bytes).digest('hex'),mode:stat.mode&0o777};
+  }catch(error){if(error.configurationError)throw error;fail('Project settings could not be read. Check configuration and file permissions.');}
+  finally{if(fd!==undefined)closeSync(fd);}
+}
+export function editProjectDocument(projectRoot,expectedDigest,apply){
+  if(!/^sha256:[a-f0-9]{64}$/.test(String(expectedDigest??'')))fail('Reload settings before saving.',400);
+  const paths=projectPaths(projectRoot),lock=paths.configPath+'.configuration.lock';let lockFd,tempFd,temporary;
+  try{
+    safePath(paths);
+    if(existsSync(paths.configPath+'.dashboard-preferences.lock'))fail('Settings are being edited. Retry after that save finishes.');
+    try{lockFd=openSync(lock,'wx',0o600);}catch{fail('Settings are being edited. Retry after that save finishes.');}
+    const before=readProjectDocument(projectRoot);if(before.digest!==expectedDigest)fail('Project configuration changed. Reload the settings and try again.');
+    apply(before.document,before.config);
+    const content=before.document.toString();
+    temporary=paths.configPath+'.settings-'+randomUUID()+'.tmp';tempFd=openSync(temporary,'wx',before.mode);
+    writeFileSync(tempFd,content,'utf8');fsyncSync(tempFd);closeSync(tempFd);tempFd=undefined;
+    if(readProjectDocument(projectRoot).digest!==before.digest)fail('Project configuration changed. Reload the settings and try again.');
+    safePath(paths);renameSync(temporary,paths.configPath);temporary=undefined;
+    return readProjectDocument(projectRoot);
+  }catch(error){if(error.configurationError||error.codingProviderError||error.dashboardPreferenceError)throw error;fail('Project settings could not be saved. Check configuration and file permissions.');}
+  finally{if(tempFd!==undefined)closeSync(tempFd);if(temporary)unlinkSync(temporary);if(lockFd!==undefined){closeSync(lockFd);unlinkSync(lock);}}
+}

package/src/dashboard-preferences.mjs

@@ -1,8 +1,4 @@
-import {constants,openSync,closeSync,fstatSync,lstatSync,readFileSync,writeFileSync,renameSync,unlinkSync,realpathSync,fsyncSync} from 'node:fs';
-import {dirname,relative,resolve,isAbsolute} from 'node:path';
-import {createHash,randomUUID} from 'node:crypto';
-import YAML from 'yaml';
-import {projectPaths} from './paths.mjs';
+import {readProjectDocument,editProjectDocument} from './config-document.mjs';
 
 export const DASHBOARD_VIEWS=Object.freeze([
   ['portfolio','Portfolio','Compare work and decisions across several projects.','Across projects and teams'],
@@ -27,54 +23,17 @@ export function normaliseDashboardPreferences(value={}){
   return {sidebar_collapsed:value.sidebar_collapsed??false,optional_views:Object.fromEntries(DASHBOARD_VIEWS.map(v=>[v.id,optional[v.id]??false]))};
 }
 export function premiumPersonasActive(premium){return premium?.access==='available'&&premium?.installed===true&&premium?.verified===true;}
-const digest=bytes=>'sha256:'+createHash('sha256').update(bytes).digest('hex');
-function safePath(paths){
-  const root=realpathSync(paths.projectRoot),parent=dirname(paths.configPath),rel=relative(root,realpathSync(parent));
-  if(rel.startsWith('..')||isAbsolute(rel))fail('Dashboard preferences require a safe project configuration path.',403);
-  let cursor=parent;
-  while(cursor!==paths.projectRoot){if(lstatSync(cursor).isSymbolicLink())fail('Dashboard preferences cannot use a symbolic configuration directory.',403);const next=dirname(cursor);if(next===cursor)fail('Dashboard preferences require a safe project configuration path.',403);cursor=next;}
-  const stat=lstatSync(paths.configPath);
-  if(!stat.isFile()||stat.isSymbolicLink()||stat.nlink!==1)fail('Dashboard preferences require a regular, non-symbolic configuration file.',403);
-  if(stat.size>2*1024*1024)fail('The project configuration is too large for dashboard preference editing.',413);
-  return stat;
-}
-function snapshot(paths){
-  const stat=safePath(paths);let fd;
-  try{
-    fd=openSync(paths.configPath,constants.O_RDONLY|constants.O_NOFOLLOW);
-    const opened=fstatSync(fd);if(opened.ino!==stat.ino||opened.dev!==stat.dev)fail('Project configuration changed. Reload the settings and try again.',409);
-    const bytes=readFileSync(fd);if(bytes.length>2*1024*1024)fail('The project configuration is too large for dashboard preference editing.',413);
-    const document=YAML.parseDocument(bytes.toString('utf8'));
-    if(document.errors.length)fail('The project configuration contains invalid YAML. Fix it before editing dashboard preferences.',422);
-    let config;try{config=document.toJS({maxAliasCount:100});}catch{fail('The project configuration cannot be safely read.',422);}
-    if(config?.schema!=='ewai.project/v1'||config?.specs?.root!==paths.specsRelative)fail('The project configuration and SPECS locator must agree before editing dashboard preferences.',422);
-    return {document,preferences:normaliseDashboardPreferences(config.dashboard),digest:digest(bytes),mode:stat.mode&0o777};
-  }finally{if(fd!==undefined)closeSync(fd);}
-}
-function guarded(operation){try{return operation();}catch(error){if(error.dashboardPreferenceError)throw error;fail('Dashboard preferences could not be read or saved. Check the project configuration and file permissions.',409);}}
+function snapshot(projectRoot){const state=readProjectDocument(projectRoot);return {...state,preferences:normaliseDashboardPreferences(state.config.dashboard)};}
+function guarded(operation){try{return operation();}catch(error){if(error.dashboardPreferenceError||error.configurationError)throw error;fail('Dashboard preferences could not be read or saved. Check project configuration and file permissions.',409);}}
 function projection(state){return {schema:'ewai.dashboard-preferences/v1',digest:state.digest,preferences:state.preferences,views:DASHBOARD_VIEWS};}
-export function readDashboardPreferences(projectRoot){return guarded(()=>projection(snapshot(projectPaths(projectRoot))));}
+export function readDashboardPreferences(projectRoot){return guarded(()=>projection(snapshot(projectRoot)));}
 export function saveDashboardPreferences(projectRoot,input){
   return guarded(()=>{
     keys(input,['confirmed','expectedDigest','preferences']);
     if(input.confirmed!==true)fail('Confirm the dashboard preference changes before saving.');
-    if(!/^sha256:[a-f0-9]{64}$/.test(String(input.expectedDigest??'')))fail('Reload dashboard preferences before saving.');
     if(!record(input.preferences))fail('Provide the dashboard preferences to save.');
-    const preferences=normaliseDashboardPreferences(input.preferences),paths=projectPaths(projectRoot);
-    safePath(paths);const lock=paths.configPath+'.dashboard-preferences.lock';let lockFd,tempFd,temporary;
-    try{
-      try{lockFd=openSync(lock,'wx',0o600);}catch{fail('Dashboard preferences are being edited. Retry after that save finishes.',409);}
-      const before=snapshot(paths);if(before.digest!==input.expectedDigest)fail('Project configuration changed. Reload the settings and try again.',409);
-      before.document.set('dashboard',preferences);const content=before.document.toString();
-      temporary=paths.configPath+'.dashboard-'+randomUUID()+'.tmp';tempFd=openSync(temporary,'wx',before.mode);
-      writeFileSync(tempFd,content,'utf8');fsyncSync(tempFd);closeSync(tempFd);tempFd=undefined;
-      if(snapshot(paths).digest!==before.digest)fail('Project configuration changed. Reload the settings and try again.',409);
-      safePath(paths);renameSync(temporary,paths.configPath);temporary=undefined;
-      return projection(snapshot(paths));
-    }finally{
-      if(tempFd!==undefined)closeSync(tempFd);
-      if(temporary)unlinkSync(temporary);
-      if(lockFd!==undefined){closeSync(lockFd);unlinkSync(lock);}
-    }
+    const preferences=normaliseDashboardPreferences(input.preferences);
+    const state=editProjectDocument(projectRoot,input.expectedDigest,document=>document.set('dashboard',preferences));
+    return projection({...state,preferences:normaliseDashboardPreferences(state.config.dashboard)});
   });
 }

package/src/delivery.mjs

@@ -10,6 +10,7 @@ import {
 import { dirname, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import YAML from 'yaml';
+import {codingPolicyDigest,assertCodingPolicyFresh,assertModelPolicy} from './coding-providers.mjs';
 import { updateIntentDeliveryState, validateIntentStateCopies } from './intents.mjs';
 import { loadProjectConfig } from './project.mjs';
 import { readRuntimeIntent } from './runtime/intents.mjs';
@@ -38,7 +39,7 @@ import { validatePhaseArtefacts } from './delivery-artifacts.mjs';
 import {
   canonicalValidationProvider,
   effectiveValidationConfig,
-  VALIDATION_PROVIDERS,
+  SUPPORTED_VALIDATION_PROVIDERS,
   validationCheckpointForPhase,
 } from './validation-config.mjs';
 import {
@@ -431,7 +432,7 @@ function normaliseDeliveryValidation(paths, state) {
   const legacyProviders = [...new Set(
     (Array.isArray(state.providers) ? state.providers : [])
       .map(canonicalValidationProvider)
-      .filter((provider) => VALIDATION_PROVIDERS.includes(provider)),
+      .filter((provider) => SUPPORTED_VALIDATION_PROVIDERS.includes(provider)),
   )];
 
   for (const [checkpointName, checkpoint] of Object.entries(validation.checkpoints)) {
@@ -638,6 +639,10 @@ function recordOwnedExternalValidationCycle(projectRoot, slug, phaseId, input) {
   const phase = findTrackedPhase(state, phaseId);
   if (phase.status !== 'running') throw new Error(`Phase ${phaseId} is not running.`);
   if (!phase.validation) throw new Error(`Phase ${phaseId} is not an external-validation checkpoint.`);
+  if(state.validation?.codingPolicyDigest){
+    const {config}=loadProjectConfig(projectRoot);
+    assertCodingPolicyFresh(state.validation.codingPolicyDigest,codingPolicyDigest(config.coding_providers));
+  }
 
   const provider = String(input.provider ?? '').trim().toLowerCase();
   if (!phase.validation.providers.includes(provider)) {
@@ -646,6 +651,7 @@ function recordOwnedExternalValidationCycle(projectRoot, slug, phaseId, input) {
     );
   }
   const outcome = String(input.outcome ?? '').trim().toLowerCase();
+  assertModelPolicy(provider,state.validation?.codingPolicy);
   if (!['pass', 'issues'].includes(outcome)) {
     throw new Error('Validation cycle outcome must be pass or issues.');
   }

package/src/discovery.mjs

@@ -20,6 +20,7 @@ import { loadProjectConfig } from './project.mjs';
 import {
   VALIDATION_CHECKPOINTS,
   VALIDATION_PROVIDERS,
+  SUPPORTED_VALIDATION_PROVIDERS,
   normaliseValidationConfig,
 } from './validation-config.mjs';
 import { publishLifecycleEventSafely } from './runtime/lifecycle-hooks.mjs';
@@ -218,7 +219,7 @@ function normaliseOrganisationBlueprint(value) {
 
 function discoveryValidation(raw, configured) {
   const rawProviders = raw.providers ?? Object.fromEntries(
-    VALIDATION_PROVIDERS
+    SUPPORTED_VALIDATION_PROVIDERS
       .filter((provider) => raw[provider] !== undefined)
       .map((provider) => [provider, raw[provider]]),
   );
@@ -852,7 +853,7 @@ function renderDiscoveryEvidence(answers, detected, standards, compliance, compl
     ['AI features', answers.assurance.aiFeatures],
     ['Accessibility obligations', answers.assurance.accessibility],
     ['Availability', answers.assurance.availability],
-    ...VALIDATION_PROVIDERS.map((provider) => [
+    ...Object.keys(answers.validation.external.providers).map((provider) => [
       `${provider[0].toUpperCase()}${provider.slice(1)} external validation`,
       `${answers.validation.external.providers[provider].state}; ${
         answers.validation.external.providers[provider].enabled ? 'enabled' : 'disabled'
@@ -879,7 +880,7 @@ function renderProjectConstraints(answers, completedAt) {
 }
 
 function renderApproach(answers, completedAt) {
-  const providerLines = VALIDATION_PROVIDERS.map((provider) => {
+  const providerLines = Object.keys(answers.validation.external.providers).map((provider) => {
     const setting = answers.validation.external.providers[provider];
     return `- **${provider[0].toUpperCase()}${provider.slice(1)}:** ${setting.state}; ${setting.enabled ? 'enabled' : 'disabled'}`;
   }).join('\n');
@@ -1250,7 +1251,7 @@ export async function runDiscoveryInterview(projectRoot, io = {}) {
     const availability = await askEnum(rl, 'Availability expectation', [...AVAILABILITY_LEVELS], 'standard');
     const configuredProviders = config.validation?.external?.providers ?? {};
     const validationProviders = {};
-    for (const provider of VALIDATION_PROVIDERS) {
+    for (const provider of [...VALIDATION_PROVIDERS,...(configuredProviders.grok?['grok']:[])]) {
       const label = `${provider[0].toUpperCase()}${provider.slice(1)}`;
       validationProviders[provider] = await askEnum(
         rl,

package/src/grok-credentials.mjs

@@ -0,0 +1,95 @@
+import {constants,openSync,closeSync,fstatSync,lstatSync,realpathSync,readFileSync,mkdirSync,writeFileSync,renameSync,unlinkSync,rmSync} from 'node:fs';
+import {homedir} from 'node:os';
+import {resolve,relative,isAbsolute} from 'node:path';
+import {randomUUID,createHash} from 'node:crypto';
+
+const messages={
+ 'grok-credential-invalid':'Provide a valid xAI API key using the private setup form or hidden terminal prompt.',
+ 'grok-credential-input':'Use the supported credential action and confirm the change.',
+ 'grok-credential-unsafe-storage':'Private credential storage is unsafe or unavailable. Repair its permissions or use XAI_API_KEY in the launching environment.',
+ 'grok-credential-invalid-storage':'The saved credential could not be read safely. Repair the private credential file before continuing.',
+ 'grok-credential-stale':'The saved credential changed. Refresh its status and try again.',
+ 'grok-credential-busy':'Another credential change is running. Retry after it finishes.',
+ 'grok-credential-missing':'No Grok key is configured. Use private credential setup or XAI_API_KEY in the launching environment.',
+ 'grok-key-rejected':'The key was not accepted. Check the key and its API permissions, then try again. The previous saved key was retained.',
+ 'grok-check-rate-limited':'xAI limited the authentication check. Wait before trying again. The previous saved key was retained.',
+ 'grok-check-unavailable':'The authentication check could not complete. Check your connection and try again. The previous saved key was retained.',
+};
+function fail(code,statusCode=400){const error=new Error(messages[code]??messages['grok-credential-input']);error.code=code;error.statusCode=statusCode;throw error;}
+function key(value){if(typeof value!=='string'||value.length>512||!/^xai-[A-Za-z0-9_-]{16,508}$/.test(value.trim()))fail('grok-credential-invalid');return value.trim();}
+function request(input,fields){if(!input||typeof input!=='object'||Array.isArray(input)||Object.keys(input).some(k=>!fields.includes(k))||input.confirmed!==true||typeof input.expectedRevision!=='string'||input.expectedRevision.length>80)fail('grok-credential-input');}
+function stat(path){try{return lstatSync(path);}catch(error){if(error.code==='ENOENT')return null;fail('grok-credential-unsafe-storage');}}
+function owned(s){return s&&!s.isSymbolicLink()&&(process.getuid===undefined||s.uid===process.getuid());}
+function paths(options={},create=false){
+ const declaredHome=resolve(options.home??homedir());
+ const root=stat(declaredHome);if(!owned(root)||!root.isDirectory()||(root.mode&0o022))fail('grok-credential-unsafe-storage');
+ let home,project;try{home=realpathSync(declaredHome);if(options.projectRoot)project=realpathSync(resolve(options.projectRoot));}catch{fail('grok-credential-unsafe-storage');}
+ const folder=resolve(home,'.ewai/credentials'),file=resolve(folder,'grok.json');
+ if(project){const rel=relative(project,file);if(rel===''||(!isAbsolute(rel)&&rel!=='..'&&!rel.startsWith('../')))fail('grok-credential-unsafe-storage');}
+ const canonicalRoot=stat(home);if(!owned(canonicalRoot)||canonicalRoot.ino!==root.ino||canonicalRoot.dev!==root.dev)fail('grok-credential-unsafe-storage');
+ for(const path of [resolve(home,'.ewai'),folder]){
+  let s=stat(path);if(!s&&create){try{mkdirSync(path,{mode:0o700});}catch(error){if(error.code!=='EEXIST')fail('grok-credential-unsafe-storage');}s=stat(path);}
+  if(s&&(!owned(s)||!s.isDirectory()||(s.mode&(path===folder?0o077:0o022))))fail('grok-credential-unsafe-storage');
+ }
+ return {folder,file,location:JSON.stringify([home,root.dev,root.ino])};
+}
+function stored(options={}){
+ const {file,location}=paths(options),before=stat(file);if(!before)return {value:null,signature:'missing',location};
+ if(process.platform==='win32'||!owned(before)||!before.isFile()||before.nlink!==1||(before.mode&0o077)||before.size>4096)fail('grok-credential-unsafe-storage');
+ let fd;try{
+  fd=openSync(file,constants.O_RDONLY|constants.O_NOFOLLOW);const bytes=readFileSync(fd),after=fstatSync(fd),current=stat(file);
+  if(bytes.length>4096||!current||before.ino!==after.ino||before.dev!==after.dev||before.mtimeMs!==after.mtimeMs||after.ino!==current.ino||after.mtimeMs!==current.mtimeMs)fail('grok-credential-unsafe-storage');
+  let value;try{value=JSON.parse(bytes.toString('utf8'));}catch{fail('grok-credential-invalid-storage');}
+  if(value?.schema!=='ewai.grok-credential/v1'||typeof value.revision!=='string'||!/^[a-f0-9-]{36}$/.test(value.revision)||Object.keys(value).some(k=>!['schema','revision','apiKey'].includes(k)))fail('grok-credential-invalid-storage');
+  try{key(value.apiKey);}catch{fail('grok-credential-invalid-storage');}
+  return {value,location,signature:JSON.stringify([after.dev,after.ino,after.mtimeMs,after.ctimeMs,createHash('sha256').update(bytes).digest('hex')])};
+ }catch(error){if(error.code?.startsWith('grok-'))throw error;fail('grok-credential-unsafe-storage');}finally{if(fd!==undefined)closeSync(fd);}
+}
+function environment(options){const env=options.env??process.env;return env.XAI_API_KEY?key(env.XAI_API_KEY):null;}
+export function grokCredentialStatus(options={}){
+ const {value}=stored(options),override=environment(options);
+ return {schema:'ewai.grok-credential-status/v1',provider:'grok',configured:Boolean(override||value),saved:Boolean(value),source:override?'environment':value?'saved':'missing',revision:value?.revision??'missing',storage:'owner-only-local-file',encrypted:false,storageSupported:process.platform!=='win32',authority:'credentials-only'};
+}
+export function resolveGrokApiKey(options={}){const override=environment(options);return override??stored(options).value?.apiKey??null;}
+function predecessor(input,options,expected){const current=stored(options);if((current.value?.revision??'missing')!==input.expectedRevision||(expected&&(current.signature!==expected.signature||current.location!==expected.location)))fail('grok-credential-stale',409);return current;}
+function mutation(options,operation){
+ if(process.platform==='win32')fail('grok-credential-unsafe-storage');
+ const {folder}=paths(options,true),lock=resolve(folder,'.grok.lock');
+ try{mkdirSync(lock,{mode:0o700});}catch(error){fail(error.code==='EEXIST'?'grok-credential-busy':'grok-credential-unsafe-storage',409);}
+ const identity=lstatSync(lock);
+ try{return operation();}finally{const current=stat(lock);if(owned(current)&&current.isDirectory()&&current.ino===identity.ino)rmSync(lock,{recursive:true});}
+}
+async function authenticate(apiKey,options={}){
+ const controller=new AbortController();let timer;
+ try{
+  const timeout=Math.min(10000,Math.max(10,options.timeoutMs??10000));
+  const response=await Promise.race([(options.fetchImpl??fetch)('https://api.x.ai/v1/models',{method:'GET',headers:{authorization:'Bearer '+apiKey},redirect:'manual',signal:controller.signal}),new Promise((_,reject)=>{timer=setTimeout(()=>{controller.abort();reject(Error('deadline'));},timeout);})]);
+  // Discard provider bodies, including errors. They are not safe evidence.
+  if(response.body)void response.body.cancel().catch(()=>{});
+  if(response.status===200)return {status:'verified',code:'grok-authentication-verified',message:'xAI authentication check passed. No output was generated; credit and coding readiness remain unverified.'};
+  const code=[401,403].includes(response.status)?'grok-key-rejected':response.status===429?'grok-check-rate-limited':'grok-check-unavailable';return {status:'failed',code,message:messages[code]};
+ }catch{return {status:'failed',code:'grok-check-unavailable',message:messages['grok-check-unavailable']};}
+ finally{clearTimeout(timer);controller.abort();}
+}
+export async function checkGrokConnection(options={}){
+ const apiKey=resolveGrokApiKey(options);
+ if(!apiKey)return {...grokCredentialStatus(options),status:'failed',code:'grok-credential-missing',message:messages['grok-credential-missing']};
+ return {...grokCredentialStatus(options),...await authenticate(apiKey,options)};
+}
+export async function configureGrokCredentials(input,options={}){
+ request(input,['confirmed','expectedRevision','apiKey']);const apiKey=key(input.apiKey);environment(options);const previous=predecessor(input,options);
+ const check=await authenticate(apiKey,options);if(check.status!=='verified')fail(check.code);
+ mutation(options,()=>{
+  predecessor(input,options,previous);const {file}=paths(options,true),temporary=file+'.'+randomUUID()+'.tmp';
+  try{writeFileSync(temporary,JSON.stringify({schema:'ewai.grok-credential/v1',revision:randomUUID(),apiKey})+'\n',{flag:'wx',mode:0o600});paths(options);predecessor(input,options,previous);renameSync(temporary,file);}
+  catch(error){if(error.code?.startsWith('grok-'))throw error;fail('grok-credential-unsafe-storage');}
+  finally{if(stat(temporary))unlinkSync(temporary);}
+ });
+ return {...grokCredentialStatus(options),check,message:'Grok key checked and saved for your account on this computer. No work started.'};
+}
+export function removeGrokCredentials(input,options={}){
+ request(input,['confirmed','expectedRevision']);environment(options);const previous=predecessor(input,options);
+ mutation(options,()=>{const current=predecessor(input,options,previous);if(current.value)unlinkSync(paths(options).file);});
+ const status=grokCredentialStatus(options);return {...status,message:status.source==='environment'?'Saved key removed. XAI_API_KEY still supplies the active credential.':'Saved Grok key removed. No work started.'};
+}
+export function safeGrokCredentialError(error){const code=Object.hasOwn(messages,error?.code)?error.code:'grok-credential-input';return {error:messages[code],code};}

package/src/install.mjs

@@ -31,11 +31,12 @@ function availableClaudeAgents() {
     .sort();
 }
 
-function selectedHosts(host, home) {
+function selectedHosts(host, home, grokHome) {
   if (host !== 'auto') return [host];
   const hosts = [];
   if (existsSync(resolve(home, '.codex'))) hosts.push('codex');
   if (existsSync(resolve(home, '.claude'))) hosts.push('claude');
+  if (existsSync(grokHome)) hosts.push('grok');
   if (
     existsSync(resolve(home, '.gemini/antigravity-cli'))
     || existsSync(resolve(home, '.gemini/config'))
@@ -43,13 +44,15 @@ function selectedHosts(host, home) {
   return hosts.length ? hosts : ['codex'];
 }
 
-function skillDestinationRoot({ scope, host, home, projectRoot }) {
+function skillDestinationRoot({ scope, host, home, projectRoot, grokHome }) {
   if (scope === 'project') {
     if (!projectRoot) throw new Error('Project installation requires projectRoot');
+    if (host === 'grok') return resolve(projectRoot, '.grok/skills');
     return host === 'claude'
       ? resolve(projectRoot, '.claude/skills')
       : resolve(projectRoot, '.agents/skills');
   }
+  if (host === 'grok') return resolve(grokHome, 'skills');
   return host === 'claude'
     ? resolve(home, '.claude/skills')
     : host === 'antigravity'
@@ -103,9 +106,11 @@ export function install(options = {}) {
   if (!['global', 'project'].includes(scope)) throw new Error(`Unsupported install scope: ${scope}`);
   if (!['copy', 'link'].includes(mode)) throw new Error(`Unsupported install mode: ${mode}`);
 
-  const hosts = selectedHosts(options.host ?? 'auto', home);
+  // Explicit fixture homes never inherit the real machine's GROK_HOME.
+  const grokHome=resolve(options.grokHome ?? (options.home===undefined ? (options.env??process.env).GROK_HOME : undefined) ?? resolve(home,'.grok'));
+  const hosts = selectedHosts(options.host ?? 'auto', home, grokHome);
   for (const host of hosts) {
-    if (!['codex', 'claude', 'antigravity'].includes(host)) throw new Error(`Unsupported agent host: ${host}`);
+    if (!['codex', 'claude', 'antigravity', 'grok'].includes(host)) throw new Error(`Unsupported agent host: ${host}`);
   }
 
   const results = [];
@@ -115,6 +120,7 @@ export function install(options = {}) {
       scope,
       host,
       home,
+      grokHome,
       projectRoot: options.projectRoot ? resolve(options.projectRoot) : ''
     });
     mkdirSync(destinationRoot, { recursive: true });

package/src/project.mjs

@@ -4,6 +4,7 @@ import { basename, dirname, extname, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import YAML from 'yaml';
 import {normaliseDashboardPreferences} from './dashboard-preferences.mjs';
+import {normaliseCodingProviders} from './coding-providers.mjs';
 import { projectPaths } from './paths.mjs';
 import { premiumPersonaLearningAction } from './companion-opening.mjs';
 import { initializeRuntime } from './runtime/database.mjs';
@@ -360,11 +361,11 @@ export function configureValidationCheckpoint(projectRoot, checkpoint, update) {
 }
 
 export function externalValidationStatus(config, orchestrator = 'manual') {
-  const effective = effectiveValidationConfig(config, orchestrator);
+  const effective = validationStatus(config, orchestrator);
   const selected = new Set(
     Object.values(effective.checkpoints).flatMap((checkpoint) => checkpoint.validators),
   );
-  return VALIDATION_PROVIDERS.map((validator) => ({
+  return Object.keys(effective.providers).map((validator) => ({
     validator,
     state: effective.providers[validator].state,
     enabled: effective.providers[validator].enabled,
@@ -374,6 +375,12 @@ export function externalValidationStatus(config, orchestrator = 'manual') {
 }
 
 export function validationStatus(config, orchestrator = 'manual') {
+  // Settings inspection has no coding-agent identity. Resolve independent
+  // roles only for an actual delivery host; phase dispatch still uses the
+  // strict effective configuration and cannot claim independence from manual.
+  if(orchestrator==='manual'&&config.coding_providers){
+    return {...effectiveValidationConfig(config.validation,orchestrator),roleResolution:'requires-orchestrator'};
+  }
   return effectiveValidationConfig(config, orchestrator);
 }
 
@@ -406,6 +413,7 @@ export function loadProjectConfig(projectRoot) {
   }
   config.validation = normaliseValidationConfig(config.validation);
   config.dashboard = normaliseDashboardPreferences(config.dashboard);
+  if(config.coding_providers!==undefined)config.coding_providers=normaliseCodingProviders(config.coding_providers);
   return { config, paths };
 }