@awebai/oats 0.25.8 → 0.26.0

package/capabilities/oats-aweb/injects/aweb.md

@@ -8,8 +8,13 @@ Some instances serve a resident global identity through an expiring session
 grant instead of holding their own root keys. In that mode, your TASK.md and
 `instance.json` identify the resident alias, scopes, and expiry; root keys are
 not in your home, and mint/revoke/join/identity-lifecycle commands are not yours
-to run. If `aw mail` or `aw chat` says the grant expired or was revoked, stop
-messaging and report the condition to your coordinator/human.
+to run. Your grant home is attached to the resident's custody service; if a
+message you sent shows unverified at the receiver, the attachment is missing:
+report it, do not retry. If `aw mail` or `aw chat` reports a terminal grant condition —
+`grant_expired`, `grant_revoked`, `grant_subject_inactive`,
+`grant_issuer_revoked`, or `grant_freshness_unavailable` — report the exact
+condition to your coordinator/human and stop using messaging. The host restarts
+you with a fresh grant when renewal is available.
 
 **Load the skills at the right moments — do not work from memory:**
 

package/capabilities/oats-aweb/lib/binding-wire.mjs

@@ -1,5 +1,9 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
 import { TextDecoder } from 'node:util';
 import { assessCapturedSessionReadiness } from './session-readiness.mjs';
+import { custodyPreflight } from './grant-custody.mjs';
 import {
   MESSAGING_CONTRACT,
   MESSAGING_CONTRACT_VERSION,
@@ -76,17 +80,24 @@ export function parseBindingJson(bytes,limits=BINDING_WIRE_LIMITS) {
   let text;try{text=new TextDecoder('utf-8',{fatal:true}).decode(bytes);}catch{wireError('invalid-binding');}
   return new StrictJsonParser(text,limits).parse();
 }
-function settings(value) {
+function settings(value,{phase}={}) {
   if(!obj(value)) wireError('invalid-binding');
-  if(Object.hasOwn(value,'identity')) wireError('provider-not-qualified');
-  keys(value,['delivery'],[]);
+  if(phase!=='check' && Object.hasOwn(value,'identity')) wireError('provider-not-qualified');
+  keys(value,phase==='check'?['delivery','team','root','roots','identity','residents']:['delivery','team','root','roots'],[]);
   if(value.delivery!==undefined && !['channel','session'].includes(value.delivery)) wireError('needs-configuration');
+  if(value.team!==undefined && (typeof value.team!=='string' || !value.team.trim())) wireError('needs-configuration');
+  if(value.root!==undefined && (typeof value.root!=='string' || !value.root.trim())) wireError('needs-configuration');
+  if(value.roots!==undefined && !obj(value.roots)) wireError('needs-configuration');
+  if(obj(value.roots)) for(const [team,root] of Object.entries(value.roots)) if(!team || typeof root!=='string' || !root.trim()) wireError('needs-configuration');
+  if(value.identity!==undefined && !obj(value.identity)) wireError('needs-configuration');
+  if(value.residents!==undefined && !obj(value.residents)) wireError('needs-configuration');
+  if(obj(value.residents)) for(const [name,custody] of Object.entries(value.residents)) if(!name || typeof custody!=='string' || !custody.trim()) wireError('needs-configuration');
   return value;
 }
 function request(value,phase) {
   keys(value,['schemaVersion','phase','slot','capability','settings','input'],['schemaVersion','phase','slot','capability','settings','input']);
   if(value.schemaVersion!==1 || value.phase!==phase || value.slot!==SLOT || value.capability!==CAPABILITY) wireError('invalid-binding');
-  settings(value.settings);return value;
+  settings(value.settings,{phase});return value;
 }
 function declaration(value) {
   keys(value,['kind','value','origin','origins'],['kind','value','origin','origins']);
@@ -142,14 +153,105 @@ function binding(value) {
   return value;
 }
 function checkResult(message) {return {status:'needs-configuration',problems:[{code:'needs-configuration',message}]};}
+function checkProblems(problems) {return problems.length?{status:'needs-configuration',problems}:null;}
+function workspaceReadinessContext(value) {
+  keys(value,['kind','workspace','deployment','soul','team','instance','home'],['kind','workspace','deployment','soul']);
+  if(value.kind!=='workspace' || typeof value.workspace!=='string' || !value.workspace.trim() || typeof value.deployment!=='string' || !value.deployment.trim() || typeof value.soul!=='string' || !value.soul.trim()) wireError('invalid-binding');
+  if(value.team!==null && value.team!==undefined && (typeof value.team!=='string' || !value.team.trim())) wireError('invalid-binding');
+  if(value.instance!==null && value.instance!==undefined && (typeof value.instance!=='string' || !value.instance.trim())) wireError('invalid-binding');
+  if(value.home!==null && value.home!==undefined && (typeof value.home!=='string' || !value.home.trim())) wireError('invalid-binding');
+  return value;
+}
+function yamlScalar(text,key){const m=String(text).match(new RegExp(`^${key}:\\s*["']?([^"'\\n#]+)["']?\\s*$`,'m'));return m?m[1].trim():undefined;}
+export const CUSTODY_ATTACH_MIN = '1.36.3';
+export function grantYamlCustodySocket(text) {
+  const lines=String(text??'').split(/\r?\n/);let inCustody=false,baseIndent=0;
+  for(const line of lines) {
+    const custody=/^(\s*)custody:\s*(?:#.*)?$/.exec(line);if(custody){inCustody=true;baseIndent=custody[1].length;continue;}
+    if(inCustody){const ind=/^(\s*)/.exec(line)?.[1].length||0;if(line.trim()&&ind<=baseIndent)inCustody=false;const socket=/^\s*socket_path:\s*["']?([^"'\n#]+)["']?\s*$/.exec(line);if(socket)return socket[1].trim();}
+  }
+  return undefined;
+}
+function newestGrantHome(home) {
+  if(typeof home!=='string'||!home.trim()) return null;
+  try {
+    const dirs=readdirSync(home).filter((name)=>name==='.aweb-identity'||/^\.aweb-identity-\d+$/.test(name)).map((name)=>join(home,name)).filter((p)=>{try{return statSync(p).isDirectory();}catch{return false;}}).map((p)=>{try{return {path:p,mtime:statSync(p).mtimeMs};}catch{return {path:p,mtime:0};}}).sort((a,b)=>b.mtime-a.mtime||b.path.localeCompare(a.path));
+    return dirs[0]?.path||null;
+  } catch {return null;}
+}
+function grantAttachmentProblem(home) {
+  const grantHome=newestGrantHome(home);
+  if(!grantHome) return null;
+  const grantYaml=join(grantHome,'grant.yaml');
+  if(!existsSync(grantYaml)) return null;
+  let text;try{text=readFileSync(grantYaml,'utf8');}catch{return null;}
+  if(grantYamlCustodySocket(text)) return null;
+  const id=yamlScalar(text,'grant_id')||'<unknown>';
+  return {code:'custody',message:`grant ${id} is not attached to custody; retire and respawn on aw >= ${CUSTODY_ATTACH_MIN}`};
+}
+function activeTeamAt(root){try{return yamlScalar(readFileSync(join(resolve(root),'.aw','teams.yaml'),'utf8'),'active_team')||yamlScalar(readFileSync(join(resolve(root),'.aw','teams.yaml'),'utf8'),'active');}catch{return undefined;}}
+function teamFromSettings(settings,candidate,{env=process.env}={}) {
+  const configured=typeof settings.team==='string' && settings.team.trim()?settings.team.trim():(env.OATS_TEAM_ID || env.OATS_TEAM_NAME || undefined);
+  if(configured || env.OATS_TEAM_LABEL) return configured;
+  return candidate?.root && isAbsolute(candidate.root) ? activeTeamAt(candidate.root) : undefined;
+}
+function classicEnv(env=process.env) {return !!env.OATS_TEAM_SCOPE && !(env.OATS_WORKSPACE_KEY || env.OATS_WORKSPACE_NAME || env.OATS_TEAM_LABEL);}
+function rootCandidate(settings,team,{deployment,env=process.env}={}) {
+  const roots=obj(settings.roots)?settings.roots:{};
+  if(team && typeof roots[team]==='string' && roots[team].trim()) return {root:roots[team].trim(),key:`settings.oats.aweb.roots[${JSON.stringify(team)}]`,declared:true};
+  if(typeof settings.root==='string' && settings.root.trim()) return {root:settings.root.trim(),key:'settings.oats.aweb.root',declared:true};
+  const candidates=classicEnv(env)?[env.OATS_TEAM_SCOPE,env.OATS_WORKSPACE].filter(Boolean):[env.OATS_WORKSPACE || deployment || env.OATS_TEAM_SCOPE || process.cwd()];
+  for(const root of candidates) if(isAbsolute(root) && existsSync(join(resolve(root),'.aw'))) return {root,key:'settings.oats.aweb.root',declared:false};
+  return {root:candidates[0] || process.cwd(),key:'settings.oats.aweb.root',declared:false};
+}
+function readinessDetails(settings,{deployment,env=process.env}={}) {
+  const initialTeam=typeof settings.team==='string' && settings.team.trim()?settings.team.trim():(env.OATS_TEAM_ID || env.OATS_TEAM_NAME || undefined);
+  const candidate=rootCandidate(settings,initialTeam,{deployment,env}),team=teamFromSettings(settings,candidate,{env}),problems=[];
+  if(!candidate.root || !isAbsolute(candidate.root) || !existsSync(join(resolve(candidate.root),'.aw'))) problems.push({code:'needs-configuration',message:`no messaging root at ${candidate.root?resolve(candidate.root):process.cwd()}: run oats aweb setup there or set ${candidate.key}`});
+  if(!team) problems.push({code:'needs-configuration',message:'no team: set messaging.byTeam.<label>.team in the workspace file or settings.oats.aweb.team'});
+  return {team,candidate,result:checkProblems(problems) || {status:'ready',problems:[]}};
+}
+function readinessFromSettings(settings,options) {return readinessDetails(settings,options).result;}
+function runAw(argv,cwd,{unsetEnv=[],timeout=60000}={}) {
+  const env={...process.env};for(const name of unsetEnv) delete env[name];
+  try {return execFileSync(argv[0],argv.slice(1),{cwd,env,encoding:'utf8',stdio:['ignore','pipe','pipe'],timeout}).trim();}
+  catch(e) {throw new Error(`${argv.slice(0,3).join(' ')} failed${e.status===undefined?'':` (exit ${e.status})`}`);}
+}
+function workspaceReadinessPhase(req) {
+  const ctx=workspaceReadinessContext(req.input.context);
+  if(!obj(req.input.action) || req.input.action.kind!=='readiness') wireError('invalid-binding');
+  const details=readinessDetails(req.settings,{deployment:ctx.deployment}),problems=[...details.result.problems],warnings=[];
+  const identity=obj(req.settings.identity)?req.settings.identity:{},mode=identity.mode===undefined || identity.mode===null || identity.mode===''?'local':String(identity.mode);
+  if(mode==='global') {
+    const grantProblem=grantAttachmentProblem(ctx.home);if(grantProblem) problems.push(grantProblem);
+    const resident=typeof identity.resident==='string' && identity.resident.trim()?identity.resident.trim():undefined;
+    const residents=obj(req.settings.residents)?req.settings.residents:{};
+    const custody=resident?residents[resident]:undefined;
+    if(!resident) problems.push({code:'custody',message:'identity.mode "global" requires identity.resident; set oats-local.yaml settings.oats.aweb.residents.<name> to the absolute custody directory for that resident identity'});
+    else if(typeof custody!=='string' || !isAbsolute(custody) || !existsSync(join(custody,'.aw','identity.yaml'))) problems.push({code:'custody',message:`identity.mode "global" resident ${JSON.stringify(resident)} is not resolvable; set oats-local.yaml settings.oats.aweb.residents.${resident} to an absolute custody directory whose .aw/identity.yaml exists`});
+    else if(details.team) {
+      try {
+        const preflight=custodyPreflight({custody,resident,team:details.team,e2eeRequired:identity.e2ee!==false,fatalOnError:false,runAw:(argv,cwd,options={})=>runAw(argv,cwd,{...options,timeout:20000})});
+        for(const message of preflight.warnings) warnings.push({code:'e2ee-disabled',message});
+      }
+      catch(e) {problems.push({code:'custody',message:e.message});}
+    }
+  }
+  const result=checkProblems(problems) || {status:'ready',problems:[]};
+  return {...result,warnings};
+}
 function checkPhase(req) {
-  keys(req.input,['binding','context','action','invocation'],['binding','context','action']);
+  keys(req.input,['binding','context','action','invocation'],['context','action']);
   if(!obj(req.input.action) || typeof req.input.action.kind!=='string') wireError('invalid-binding');
+  if(!Object.hasOwn(req.input,'binding')) return workspaceReadinessPhase(req);
   const current=validateAwebBinding(binding(req.input.binding)),selectedContext=context(req.input.context,{request:true});
   if(!same(selectedContext,current.payload.context)) wireError('invalid-binding');
   const invocation=Object.hasOwn(req.input,'invocation')?validateAwebInvocationContext(req.input.invocation,current,{context:req.input.context,action:req.input.action}):null;
   if(['command','hook','operation'].includes(req.input.action.kind) && (!invocation || invocation.instance===null || invocation.intent===null)) return checkResult('an admitted captured instance intent is required for execution');
   if(current.payload.privateTeam===null) return checkResult('an explicit private-team binding is required');
+  const hostReady=readinessFromSettings(req.settings);
+  if(hostReady.status!=='ready') return hostReady;
+  if(!invocation) return hostReady;
   // Read-only public kernel observations, not an account/grant attestation.
   // Native setup is performed only by the separately admitted execution path.
   return assessCapturedSessionReadiness({binding:current,invocation,settings:req.settings});

package/capabilities/oats-aweb/lib/captured-native.mjs

@@ -26,7 +26,7 @@ export function runCapturedNative({selected,event,settings,run,env=process.env})
  const refusal=(code,message)=>({exitCode:1,output:{...(meta?{meta}:{}),status:'needs-configuration',problems:[{code,message}],warning:`oats-aweb: ${message}; retain the home and any recorded partial effects`}});
  try{
   assertCurrent();
-  if(!/^[a-z0-9][a-z0-9._-]{0,127}$/i.test(name)||!team)fail('needs-configuration','exact native alias and private-team selection are required');
+  if(!/^[a-z0-9][a-z0-9_-]{0,63}$/i.test(name)||!team)fail('needs-configuration','exact native alias and private-team selection are required');
   if(settings.delivery!=='session')fail('needs-configuration','captured delivery must be session');
   if(binding.payload.wider.length)fail('needs-configuration','selected wider memberships need their explicitly qualified native setup; they were not omitted');
   // A global override may select a different actor even with an exact cwd.

package/capabilities/oats-aweb/lib/grant-custody.mjs

@@ -0,0 +1,38 @@
+export function parseAwJson(text, what) {
+  const trimmed = String(text ?? '').trim();
+  if (!trimmed) throw new Error(`${what} returned no JSON result`);
+  try { return JSON.parse(trimmed); } catch { /* may have progress before JSON */ }
+  const lines = trimmed.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    if (!lines[i].trimStart().startsWith('{')) continue;
+    try { return JSON.parse(lines.slice(i).join('\n')); } catch { /* keep looking */ }
+  }
+  throw new Error(`${what} returned no JSON result`);
+}
+
+export function custodyPreflight({ custody, resident, team, e2eeRequired = true, runAw, fatalOnError = true, fatal }) {
+  const failNow = (message) => { if (fatalOnError && typeof fatal === 'function') fatal(message); throw new Error(message); };
+  let status;
+  try { status = parseAwJson(runAw(['aw', 'custody', 'status', '--json'], custody, { unsetEnv: ['AWEB_IDENTITY_HOME'] }), 'aw custody status'); }
+  catch (e) { failNow(`custody preflight failed for ${resident}: aw custody status --json could not run (${e.message || e}); start aw custody serve for ${resident}`); }
+  const state = String(status.status || 'unknown');
+  const firstError = Array.isArray(status.errors) && status.errors.length ? status.errors[0] : undefined;
+  const firstErrorCode = typeof firstError === 'string' ? firstError : firstError?.code;
+  const code = firstErrorCode ? ` error=${firstErrorCode}` : '';
+  const fail = (why) => failNow(`custody preflight failed for ${resident}: status=${state}${code}; ${why}; start aw custody serve for ${resident}`);
+  if (state !== 'running') fail('custody service is not running');
+  const teamRow = (Array.isArray(status.teams) ? status.teams : []).find((t) => t && (t.team_id || t.id) === team);
+  if (!teamRow) fail(`team ${team} is not present in custody status`);
+  if (teamRow.ready !== true) fail(`team ${team} is not ready in custody status`);
+  if (teamRow.certificate_present === false) fail(`team ${team} certificate is not present in custody status`);
+  if (teamRow.grant_status_endpoint_ready !== undefined && teamRow.grant_status_endpoint_ready !== true) fail(`the aweb server serving team ${team} does not provide grant status yet; hosted grants wait for that deployment`);
+  if (status.keys?.signing_ready !== true) fail('keys.signing_ready is false');
+  const ops = new Set(Array.isArray(status.ops) ? status.ops.map(String) : []);
+  const requiredOps = ['sign_plain_message.v1', ...(e2eeRequired ? ['unwrap_e2ee_message.v1', 'create_e2ee_envelope.v1'] : [])];
+  const missingOps = requiredOps.filter((op) => !ops.has(op));
+  if (missingOps.length) fail(`required custody operations are missing: ${missingOps.join(', ')}`);
+  if (e2eeRequired && status.keys?.encryption_ready !== true) fail('keys.encryption_ready is false');
+  const warnings = [];
+  if (!e2eeRequired && status.keys?.encryption_ready !== true) warnings.push('E2E encryption is disabled for this grant and custody encryption is not ready; encrypted mail/chat will not be available in this session.');
+  return { status, warnings };
+}

package/capabilities/oats-aweb/oats.json

@@ -1,9 +1,9 @@
 {
   "capability": "oats.aweb",
   "command": "aweb",
-  "version": "1.12.0",
+  "version": "1.13.1",
   "compatibility": {
-    "oats": ">=0.24.4"
+    "oats": ">=0.25.6"
   },
   "layer": "messaging",
   "description": "Messaging layer via aweb: per-instance team identities + native aw mail/chat skills + cross-machine team roster.",
@@ -121,7 +121,8 @@
       "command": "bin/oats-aweb.mjs spawn",
       "required": true
     },
-    "retire": "bin/oats-aweb.mjs retire"
+    "retire": "bin/oats-aweb.mjs retire",
+    "launch": "bin/oats-aweb.mjs launch"
   },
   "environment": [
     "AWEB_DELIVERY",
@@ -139,13 +140,22 @@
     "team": {
       "description": "Target aweb team id for identity lifecycle. In workspace v2 spawns this payload value wins over OATS_TEAM_ID/OATS_TEAM_NAME; if both are set and differ the hook warns and uses this setting."
     },
+    "root": {
+      "hostOnly": true,
+      "description": "Host-owned absolute directory whose .aw is the aweb minting root. Put this only in oats-local.yaml settings.oats.aweb.root; use oats aweb setup to initialize it."
+    },
+    "roots": {
+      "hostOnly": true,
+      "description": "Host-owned map of aweb team id to absolute directory whose .aw is that team's minting root, for deployments that mint into several teams. Put this only in oats-local.yaml settings.oats.aweb.roots."
+    },
     "identity": {
       "default": {
         "mode": "local"
       },
-      "description": "Identity selection. mode=local (default) mints an instance-local team identity or uses the existing identity.source retained-seat flow. mode=global acts as a named resident identity through a session grant; requires identity.resident and optional scopes/ttl."
+      "description": "Identity selection. mode=local (default) mints an instance-local team identity or uses the existing identity.source retained-seat flow. mode=global acts as a named resident identity through a session grant; requires identity.resident. Optional global fields: profile (normal|reviewer), scopes (explicit concrete grant scope list, wins over profile), ttl, e2ee (default true), renew (off|launch, default off)."
     },
     "residents": {
+      "hostOnly": true,
       "description": "Host-owned map for global mode: resident name to absolute custody directory whose .aw holds the resident root keys and team certificate. Put this only in oats-local.yaml settings.oats.aweb.residents; committed workspace or soul files must never carry custody paths."
     }
   },

package/capabilities/oats-jira/bin/oats-jira.mjs

@@ -27,13 +27,13 @@ if (event === "spawn") {
   const site = settings.site;
   const project = settings.project;
   const where = site && project ? `project ${project} on ${site}`
-    : site ? `site ${site} (project unset — ask your human or check oats doctor)`
-    : project ? `project ${project} (site unset — ask your human or check oats doctor)`
-    : `your deployment's Jira (site/project not configured — ask your human, or set capabilities.oats.jira.<target>.settings in oats-config.yaml)`;
+    : site ? `site ${site} (project unset — ask your human)`
+    : project ? `project ${project} (site unset — ask your human)`
+    : `your deployment's Jira (site/project not configured — ask your human to set tasks: { site, project } in the soul's soul.yaml, or settings.oats.jira.{site,project} in the deployment's oats-local.yaml)`;
   out({
     meta: { label, ...(site ? { site } : {}), ...(project ? { project } : {}) },
     brief: `Tasks: Jira — ${where}. Your Jira identity is the label "${label}" (never the assignee field). Load the jira-tasks skill before touching tickets.`,
-    ...(site && project ? {} : { warning: `oats-jira: settings incomplete (site: ${site || "unset"}, project: ${project || "unset"}) — set capabilities.oats.jira.<target>.settings.{site,project} in oats-config.yaml` }),
+    ...(site && project ? {} : { warning: `oats-jira: settings incomplete (site: ${site || "unset"}, project: ${project || "unset"}) — set tasks: { site, project } in the soul's soul.yaml, or settings.oats.jira.{site,project} in the deployment's oats-local.yaml` }),
   });
 } else {
   warn(`unknown event "${event}" (expected spawn)`);

package/capabilities/oats-jira/oats.json

@@ -1,8 +1,8 @@
 {
   "capability": "oats.jira",
   "command": "jira",
-  "version": "1.0.0",
-  "compatibility": { "oats": ">=0.19.0" },
+  "version": "1.0.1",
+  "compatibility": { "oats": ">=0.26.0" },
   "layer": "tasks",
   "description": "Tasks layer via Jira: acli-based epic/story/task protocol, agent roster in epic descriptions, label-based agent identity.",
   "requires": [

package/capabilities/oats-jira/skills/jira-tasks/SKILL.md

@@ -29,12 +29,15 @@ tracking and the agent roster. Agents do not know about projects — you know
 
 ## Site and project (from your deployment, never hardcoded)
 
-Your Jira **site** and **project key** come from the deployment's OATS config
-(`capabilities.oats.jira.<target>.settings: { site, project }`). Find them, in order:
+Your Jira **site** and **project key** come from the tasks payload OATS merged
+for this instance: the soul's `soul.yaml` `tasks: { site, project }`, the
+deployment's `oats-local.yaml` `settings.oats.jira.{site,project}`, or a
+spawn's `--provider oats.jira key=value`. Find them, in order:
 
 1. Your `TASK.md` briefing — the spawn hook writes a
    `Tasks: Jira — project <KEY> on <site>` line.
-2. `oats doctor --json` from your work tree (the tasks layer's settings).
+2. `./instance.json` in your instance home — `providers["oats.jira"]` is the
+   merged payload this instance received.
 3. Ask your human.
 
 Below, `<PROJECT>` means that project key. If site or project are unset,

package/capabilities/oats-linear/bin/oats-linear-hook.mjs

@@ -10,23 +10,25 @@ if (event !== "spawn") output({ warning: `oats-linear: unknown event "${event}"
 
 let settings = {};
 try { settings = JSON.parse(process.env.OATS_SETTINGS || "{}"); }
-catch { output({ warning: "oats-linear: integrations.linear.settings is not valid JSON" }); }
+catch { output({ warning: "oats-linear: the tasks settings payload (OATS_SETTINGS) is not valid JSON" }); }
 
 const instance = process.env.OATS_INSTANCE || "unknown-instance";
 const team = settings.team;
 const project = settings.project;
 const label = `agent-${instance}`;
+// Where team lives under the workspace model (0.26): the soul's tasks payload or this machine's settings.
+const TEAM_HOMES = "tasks: { team } in the soul's soul.yaml, or settings.oats.linear.team in the deployment's oats-local.yaml";
 const target = team
   ? `team ${team}${project ? `, default project ${project}` : ""}`
-  : "team unset — ask your human, or set integrations.linear.settings.team in oats-config.yaml";
+  : `team unset — ask your human to set ${TEAM_HOMES}`;
 const warnings = [];
-if (!team) warnings.push("settings.team is unset");
+if (!team) warnings.push(`settings.team is unset (set ${TEAM_HOMES})`);
 if (!process.env.LINEAR_API_KEY) warnings.push("LINEAR_API_KEY is not in the spawn environment");
 
 output({
   meta: { label, ...(team ? { team } : {}), ...(project ? { project } : {}) },
   brief: `Tasks: Linear — ${target}. Your agent identity is label "${label}"; keep the human assignee unchanged. Load the linear-tasks skill before touching issues.`,
   ...(warnings.length ? {
-    warning: `oats-linear: ${warnings.join("; ")} — see capabilities/oats-linear/README.md`,
+    warning: `oats-linear: ${warnings.join("; ")} — see the linear-tasks skill`,
   } : {}),
 });

package/capabilities/oats-linear/oats.json

@@ -1,8 +1,8 @@
 {
   "capability": "oats.linear",
   "command": "linear",
-  "version": "1.0.0",
-  "compatibility": { "oats": ">=0.19.0" },
+  "version": "1.0.1",
+  "compatibility": { "oats": ">=0.26.0" },
   "layer": "tasks",
   "description": "Tasks layer via Linear: JSON-first GraphQL commands, project/issue/sub-issue workflow, label-based agent identity.",
   "requires": [],

package/capabilities/oats-linear/skills/linear-tasks/SKILL.md

@@ -23,6 +23,12 @@ Get the target from the `Tasks: Linear` line in your `TASK.md` briefing:
 - **project** is an optional deployment default. Do not invent one when unset.
 - **alias** is your exact OATS instance name; your label is `agent-<alias>`.
 
+team and project come from the tasks payload OATS merged for this instance —
+the soul's `soul.yaml` `tasks: { team, project }`, the deployment's
+`oats-local.yaml` `settings.oats.linear.*`, or a spawn's `--provider` — and
+`./instance.json` in your instance home records it as `providers["oats.linear"]`.
+If team is unset, stop and ask your human to set it there.
+
 Before the first operation, run:
 
 ```bash

package/capabilities/oats-okf/bin/oats-okf.mjs

@@ -175,7 +175,7 @@ else {
     } else if(event==='unlock') result=unlock(resolve(flags.lock),flags.token);
     else fail('E_USAGE',`unknown command ${event}; see --help`);
     answer=hook?result:{schemaVersion:1,ok:true,result};
-  } catch(e) {exit=1;answer=hook?{meta:{...(event==='retire'?{retired:false,reason:e.message}:{})},warning:`oats-okf: ${e.message}`}:{schemaVersion:1,ok:false,error:{code:e.code || 'E_OKF',message:e.message}};}
+  } catch(e) {const code=e.code || 'E_OKF';exit=1;answer=hook?{meta:{...(event==='retire'?{retired:false,reason:e.message}:{})},warning:`oats-okf ${code}: ${e.message}`}:{schemaVersion:1,ok:false,error:{code,message:e.message}};}
   // Let Node drain the pipe; no process.exit after a possibly large view.
   process.stdout.write(JSON.stringify(answer)+'\n');process.exitCode=exit;
 }

package/capabilities/oats-okf/lib/binding-wire.mjs

@@ -291,7 +291,7 @@ function checkPhase(req) {
     if(gitBases.length) scratch=fs.mkdtempSync(join(fs.realpathSync(tmpdir()),'oats-okf-binding-check-'));
     for(const [alias,base] of Object.entries(bindings.bases)) {
       stage=base.kind==='directory'?'validate':'stage';
-      accepted[alias]=(base.kind==='directory'?validateBase(base.path,base):stageBase(base,join(scratch,alias))).meta;
+      accepted[alias]=(base.kind==='directory'?validateBase(base.path,base):stageBase(base,join(scratch,alias),{alias})).meta;
     }
     stage='runtime';
     checkKnowledgeRuntime({rendered:runtime,accepted});

package/capabilities/oats-okf/lib/migration.mjs

@@ -33,7 +33,7 @@ export function migrate(bindings,{legacy,alias,node,output}) {
   // Stage the accepted base before any record exists: a base that cannot be
   // read leaves nothing behind. From the record on, a failure is recorded in
   // it rather than left as an unexplained directory.
-  const stage=stageBase(base,output);
+  const stage=stageBase(base,output,{alias});
   fs.mkdirSync(bindings.stateDir,{recursive:true,mode:0o700});
   const id=randomUUID();const dir=join(bindings.stateDir,'migrations',id);fs.mkdirSync(dir,{recursive:true,mode:0o700});
   save(join(dir,'legacy.json'),original); // byte-preserving backup BEFORE any delivery
@@ -106,7 +106,7 @@ export function cutoverMigration(file,soul) {
   try {
     for(const alias of new Set([...decl.owns,...decl.reads].map(r=>splitRef(r)[0]))) {
       if(!Object.hasOwn(bindings.bases,alias)) fail('E_CONFIG',`unresolved base: ${alias}`);
-      const staged=stageBase(bindings.bases[alias],join(scratch,alias));
+      const staged=stageBase(bindings.bases[alias],join(scratch,alias),{alias});
       accepted[alias]=staged.meta;
       if(alias===m.alias) {
         if(hash(staged.meta.nodes[m.node] || null)!==hash(frozen)) fail('E_OWNER','accepted migration ownership/path differs from delivered node');

package/capabilities/oats-okf/lib/sources.mjs

@@ -101,7 +101,7 @@ export function views(bindings, decl, target) {
     for(const [alias,base] of Object.entries(bindings.bases)) {
       const scratch=fs.mkdtempSync(join(bindings.stateDir,'read-'));
       try {
-        const staged=stageBase(base,join(scratch,'base'));
+        const staged=stageBase(base,join(scratch,'base'),{alias});
         all[alias]=staged.meta;
         const path=`bases/${alias}`;
         materialize(join(pending,path),staged.files);
@@ -192,7 +192,8 @@ export function register(home) {
   if(fs.existsSync(join(home,'knowledge'))) fail('E_VIEW','unregistered knowledge view exists; preserve it and inspect before registering');
   if(['.okf-harvest-record.json','.okf-harvest-record.next.json'].some(p=>fs.existsSync(join(home,p))) && !fs.existsSync(join(home,'.okf-v1-migration.json'))) fail('E_MIGRATION','legacy source watermarks require explicit oats okf migrate --source-home PATH before v2 registration; no cursor is silently trusted');
   const meta=fs.existsSync(join(home,'instance.json'))?readJSON(join(home,'instance.json')):{};
-  const soul=fs.realpathSync(process.env.OATS_SOUL || join(home,'soul'));
+  if(!process.env.OATS_SOUL) fail('E_OATS_SOUL_MISSING','OATS_SOUL is not set; oats.okf hooks and commands run only under the OATS kernel');
+  const soul=fs.realpathSync(process.env.OATS_SOUL);
   const work=fs.existsSync(join(home,'work'))?fs.realpathSync(join(home,'work')):join(home,'work');
   const decl=declaration(soul);
   const soulId=process.env.OATS_SOUL_ID || null;
@@ -204,7 +205,6 @@ export function register(home) {
   if(!agent || !instance) fail('E_SOURCE','source instance/agent required');
   fs.mkdirSync(bindings.stateDir,{recursive:true,mode:0o700});
   const ownersFile=join(bindings.stateDir,'owners.json');
-  pinOwner(ownersFile,decl.owner,{id:soulId,soulName:agent,path:soul});
   const id=randomUUID(); const dir=join(bindings.stateDir,'sources',id);
   // Copy only the role document, never instance.json wholesale, launch recipes,
   // environment, credentials, source worktree, or third-party message stores.
@@ -217,6 +217,7 @@ export function register(home) {
   fs.mkdirSync(dir,{recursive:true,mode:0o700});
   try {
     source.acceptedView=views(bindings,decl,pending);
+    pinOwner(ownersFile,decl.owner,{id:soulId,soulName:agent,path:soul});
     source.acceptedNodes=Object.fromEntries(Object.entries(source.acceptedView).map(([alias,r])=>[alias,r.nodes]));
     save(file,source);
     save(join(dir,'status.json'),{version:1,captured:{notes:[],threads:{},inputs:[]},processed:[],delivered:{},accepted:{},retired:false,auto:true,activeRun:null});
@@ -245,7 +246,7 @@ export function pinOwner(ownersFile,owner,{id,soulName,path}) {
     if(!obj(owners)) fail('E_OWNER','invalid owner registry');
     const prior=Object.hasOwn(owners,owner)?owners[owner]:undefined;
     const samePath=typeof prior==='string' && new RegExp(`/agents/${soulName.replace(/[.*+?^${}()|[\]\\]/g,'\\$&')}/(soul|souls/[^/]+)$`).test(prior);
-    if(prior!==undefined && prior!==value && !(id && samePath)) fail('E_OWNER','stable owner ID already identifies a different soul in this state namespace');
+    if(prior!==undefined && prior!==value && !(id && samePath)) fail('E_OWNER',`stable owner ID already identifies a different soul in this state namespace: existing soul ${prior}; new soul ${value}. Remedies: retire the existing registration first, or use a fresh state directory.`);
     if(prior!==value) {owners[owner]=value;save(ownersFile,owners);}
     return value;
   });

package/capabilities/oats-okf/lib/stores.mjs

@@ -9,6 +9,31 @@ const validator = fileURLToPath(new URL('../skills/okf/scripts/okf-validate.mjs'
 // transport subprocesses. Override even an explicitly supplied command env.
 const gitEnv = (env = cleanEnv()) => ({...env,GIT_NO_REPLACE_OBJECTS:'1'});
 export const git = (cwd,args,opts={}) => exec('git',['--no-replace-objects','-c','core.hooksPath=/dev/null','-c','protocol.ext.allow=never','-C',cwd,...args],{cwd,...opts,env:gitEnv(opts.env)});
+function baseError(code,message,base,alias,step,reason) {throw Object.assign(new Error(message),{code,base:alias,repository:base.repository,step,reason});}
+function baseRemedy(alias) {return `fix the binding for base alias "${alias}" in the bindings file, or remove the base from the bindings`;}
+function classifyGitFailure(error) {
+  const text=String(error?.message || '');
+  if(error?.code==='ETIMEDOUT' || /ETIMEDOUT|timed out|timeout/i.test(text)) return 'timeout';
+  if(/authentication|permission denied|publickey|access denied|could not read Username|authorization|not authorized/i.test(text)) return 'auth';
+  if(/not found|repository .*not exist|does not exist|no such (file|repository)|couldn't find remote ref|Repository not found/i.test(text)) return 'not-found';
+  if(/could not resolve host|failed to connect|connection refused|network is unreachable|no route to host|proxy/i.test(text)) return 'network';
+  return 'unknown';
+}
+function unavailable(base,alias,step,error) {
+  const reason=classifyGitFailure(error),detail=reason==='unknown'?`; original Git failure: ${String(error?.message || 'unknown failure')}`:'';
+  const message=`Git base "${alias}" repository "${base.repository}" is required by the deployment's bindings, but ${step} failed (reason: ${reason}${detail}); ${baseRemedy(alias)}`;
+  baseError('E_BASE_UNAVAILABLE',message,base,alias,step,reason);
+}
+function requireNotShallow(base,alias,cwd) {
+  const shallow=git(cwd,['rev-parse','--is-shallow-repository']);
+  if(shallow==='true') baseError('E_BASE_SHALLOW',`Git base "${alias}" repository "${base.repository}" is required by the deployment's bindings, but the repository is shallow; oats.okf requires full accepted history before staging; ${baseRemedy(alias)}`,base,alias,'clone','shallow');
+}
+function preflightLocalRepository(base,alias) {
+  if(!base.repository.startsWith('/')) return;
+  if(!fs.existsSync(base.repository)) unavailable(base,alias,'clone',Object.assign(new Error('repository not found'),{code:'ENOENT'}));
+  try { requireNotShallow(base,alias,base.repository); }
+  catch(e) { if(e.code==='E_BASE_SHALLOW') throw e; unavailable(base,alias,'clone',e); }
+}
 export const baseLock = b => `${b.path}.okf-lock`;
 export const journalPath = b => `${b.path}.okf-publication.json`;
 export function validateBase(root, base) {
@@ -53,9 +78,10 @@ function materializeGitObjects(base,dest,head) {
     writeBlob(dest,entry.oid,target,entry.mode==='100755'?0o755:0o644);
   }
 }
-function clone(base, dest, selectedHead) {
+function clone(base, dest, selectedHead, { alias = base.id } = {}) {
   safePath(dest);
   if(fs.existsSync(dest)) fail('E_PATH',`staging destination exists: ${dest}`);
+  preflightLocalRepository(base,alias);
   fs.mkdirSync(dirname(dest),{recursive:true});
   // Fetch only what the store reads: the accepted branch, trees now and blobs
   // on demand. Only a remote that does not offer object filtering gets a plain
@@ -64,25 +90,30 @@ function clone(base, dest, selectedHead) {
   const cloneArgs=['clone','--no-hardlinks','--no-checkout','--single-branch','--branch',base.acceptedBranch];
   try { git(dirname(dest),[...cloneArgs,'--filter=blob:none','--',base.repository,dest],{timeout:gitTimeoutMs()}); }
   catch(e) {
-    if(e.code!=='E_COMMAND' || !/filter/i.test(e.message)) throw e;
-    fs.rmSync(dest,{recursive:true,force:true});
-    git(dirname(dest),[...cloneArgs,'--',base.repository,dest],{timeout:gitTimeoutMs()});
+    if(e.code==='E_COMMAND' && /filter/i.test(e.message)) {
+      fs.rmSync(dest,{recursive:true,force:true});
+      try { git(dirname(dest),[...cloneArgs,'--',base.repository,dest],{timeout:gitTimeoutMs()}); }
+      catch(error) { unavailable(base,alias,'clone',error); }
+    } else unavailable(base,alias,'clone',e);
   }
-  git(dest,['fetch','origin',`refs/heads/${base.acceptedBranch}`],{timeout:gitTimeoutMs()});
+  try { requireNotShallow(base,alias,dest); }
+  catch(e) { if(e.code==='E_BASE_SHALLOW') throw e; unavailable(base,alias,'clone',e); }
+  try { git(dest,['fetch','origin',`refs/heads/${base.acceptedBranch}`],{timeout:gitTimeoutMs()}); }
+  catch(e) { unavailable(base,alias,'fetch',e); }
   const head=selectedHead ?? git(dest,['rev-parse','FETCH_HEAD']);
-  verifyRemote(base,dest);
-  materializeGitObjects(base,dest,head);
+  try { requireNotShallow(base,alias,dest);verifyRemote(base,dest);materializeGitObjects(base,dest,head); }
+  catch(e) { if(['E_BASE_SHALLOW','E_OWNER','E_CONFIRM','E_PATH','E_BASE','E_VALIDATION'].includes(e.code)) throw e; unavailable(base,alias,'checkout',e); }
   // Reject a linked bundle even if Git happily checked the link out.
   safePath(join(dest,base.root));
   return head;
 }
-export function stageBase(base, dest) {
+export function stageBase(base, dest, { alias = base.id } = {}) {
   safePath(dest);
   if(fs.existsSync(dest)) fail('E_PATH',`staging destination exists: ${dest}`);
   const acceptedPath=base.kind==='directory'?base.path:(base.repository.startsWith('/')?resolve(base.repository,base.root):null);
   if(acceptedPath && overlaps(acceptedPath,dest)) fail('E_PATH','stage overlaps accepted base');
   if(base.kind==='git') {
-    const head=clone(base,dest); const root=join(dest,base.root);
+    const head=clone(base,dest,undefined,{alias}); const root=join(dest,base.root);
     const validated=validateBase(root,base);
     verifyPublicationTree(base,dest,head,head,validated.files);
     return { ...validated, head, root, checkout:dest };

package/capabilities/oats-okf/lib/worker.mjs

@@ -142,7 +142,7 @@ function prepareWorker(source,run) {
   for(const [alias,base] of Object.entries(source.bindings.bases)) {
     if(run.settled?.includes(alias)) continue;
     const dest=join(work,'bases',alias);
-    const staged=stageBase(base,dest);
+    const staged=stageBase(base,dest,{alias});
     const owned=source.decl.owns.map(splitRef).filter(([a])=>a===alias).map(([,n])=>n);
     for(const n of owned) if(staged.meta.nodes[n]?.owner!==source.owner || JSON.stringify(staged.meta.nodes[n])!==JSON.stringify(source.acceptedNodes[alias][n])) fail('E_OWNER','accepted ownership/path changed from frozen destination; explicit migration required');
     run.stages[alias]={root:staged.root,checkout:staged.checkout,head:staged.head,baseline:staged.files,digest:staged.digest,owned};persist(source,run);
@@ -235,7 +235,7 @@ export function complete(source,id,judgmentFile,opts={}) {
         if(base.kind==='git') verifyGitScope(base,s.checkout,s.head);
         const checkDir=fs.mkdtempSync(join(source.bindings.stateDir,'baseline-'));
         try {
-          const current=stageBase(base,join(checkDir,'base'));
+          const current=stageBase(base,join(checkDir,'base'),{alias});
           if(current.digest!==s.digest || (base.kind==='git' && current.head!==s.head)) fail('E_BASELINE','accepted base changed; rejudge on fresh baseline');
         } finally {fs.rmSync(checkDir,{recursive:true,force:true});}
         const claims=judgment.outcomes.flatMap(o=>o.concepts).filter(c=>c.base===alias).map(c=>c.path);
@@ -310,7 +310,7 @@ export function retry(source,{run:id,rejudge=false,launch=false,adoptHome}={}) {
     const stages={...run.stages},outstanding=Object.keys(stages).filter(a=>!settled.includes(a));
     for(const alias of outstanding) {
       const base=source.bindings.bases[alias];
-      const staged=stageBase(base,join(work,'rejudgments',attempt,'bases',alias));
+      const staged=stageBase(base,join(work,'rejudgments',attempt,'bases',alias),{alias});
       const owned=run.stages[alias].owned;
       for(const n of owned) if(staged.meta.nodes[n]?.owner!==source.owner || JSON.stringify(staged.meta.nodes[n])!==JSON.stringify(source.acceptedNodes[alias][n])) fail('E_OWNER','accepted ownership/path changed from frozen destination; explicit migration required');
       stages[alias]={root:staged.root,checkout:staged.checkout,head:staged.head,baseline:staged.files,digest:staged.digest,owned};

package/capabilities/oats-okf/oats.json

@@ -1,7 +1,7 @@
 {
   "capability": "oats.okf",
   "command": "okf",
-  "version": "2.1.4",
+  "version": "2.1.5",
   "compatibility": {
     "oats": ">=0.24.4"
   },

package/capabilities/oats-review/oats.json

@@ -1,7 +1,8 @@
 {
   "capability": "oats.review",
-  "version": "1.2.0",
-  "compatibility": { "oats": ">=0.19.0" },
+  "private": true,
+  "version": "1.2.1",
+  "compatibility": { "oats": ">=0.26.0" },
   "description": "Post-commit review discipline: a fresh reviewer agent (defined by this capability) reviews each new commit's diff, reports its verdict to its spawner over the deployment's messaging layer (or in its transcript when there is none), and retires — plus the shared developer delivery discipline.",
   "requires": [],
   "agents": ["agents/reviewer"],