@awebai/oats 0.43.3 → 0.44.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/oats.mjs +98 -27
- package/docs/capabilities.md +7 -1
- package/docs/configuration.md +65 -0
- package/docs/desktop-cli-api.md +149 -4
- package/docs/desktop.md +47 -0
- package/docs/execution-targets.md +75 -0
- package/docs/implementation.md +14 -1
- package/docs/oats-local.schema.json +19 -1
- package/docs/oats-workspace.schema.json +1 -1
- package/docs/release-notes/v0.44.0.md +161 -0
- package/docs/release-notes/v0.44.1.md +47 -0
- package/docs/schedules.md +27 -9
- package/docs/souls-and-instances.md +7 -0
- package/lib/core.mjs +253 -87
- package/lib/instance-events.mjs +1 -1
- package/lib/instance-inspect.mjs +39 -6
- package/lib/launch-prompt-fixtures/README.md +49 -0
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +35 -0
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +35 -0
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +35 -0
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +35 -0
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +77 -0
- package/lib/launch-prompt-fixtures.mjs +114 -0
- package/lib/launch-prompt-policy.mjs +73 -0
- package/lib/launch-prompt-transport.mjs +102 -0
- package/lib/launch-prompts.mjs +216 -0
- package/lib/operator-coverage.mjs +134 -0
- package/lib/remote.mjs +15 -9
- package/lib/schedule.mjs +57 -10
- package/lib/teams-verbs.mjs +3 -3
- package/lib/triggers.mjs +2 -2
- package/lib/workspace.mjs +20 -2
- package/package.json +1 -1
- package/skills/oats-getting-started/SKILL.md +15 -0
package/bin/oats.mjs
CHANGED
|
@@ -5,8 +5,8 @@
|
|
|
5
5
|
* oats doctor [dir] [--soul <s>] [--json] show the deployment; --soul: the instructions an instance of <s> would carry
|
|
6
6
|
* oats onboard [<dir>] --workspace <ref> realize a workspace here (oats-local.yaml +
|
|
7
7
|
* agents/), then sync
|
|
8
|
-
* oats sync [--dir <d>] [--json]
|
|
9
|
-
* resolve packages, write the lock
|
|
8
|
+
* oats sync [--dir <d>] [--plan] [--json] discover the workspace, confirm membership,
|
|
9
|
+
* resolve packages, write the lock (--plan: write nothing)
|
|
10
10
|
* oats package add|remove ... edit `packages:` in the workspace file
|
|
11
11
|
* oats workspace status membership table, packages
|
|
12
12
|
* oats capabilities | oats souls every visible item of the workspace
|
|
@@ -30,11 +30,11 @@ import {
|
|
|
30
30
|
LAYERS, OATS_VERSION, manifestOperations, upgradeHomeMeta,
|
|
31
31
|
capabilityManifests, capabilityTrust, capabilityExecutablePath,
|
|
32
32
|
officialPackageCatalog, officialCatalogFile, officialCapabilityAliases, resolvedFromHome, resolvedFromPrepared, teamEnv, isWorkspaceHome, preWorkspaceHome, isCapturedHome, capturedHomeRefusal, composeInstanceAgentsMd, parseYamlNested, withConfigFile,
|
|
33
|
-
findInstanceHome, findInstanceHomes, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf, stopInstanceSession, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, instanceSoulDir, stableSoulId, preparedSoulIdOf, recordedKernelBin, launchConfigsAt, launchReportFor, explicitInstanceName, retireInstance, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, withSafeTaskPrompt, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
|
|
33
|
+
findInstanceHome, findInstanceHomes, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf, stopInstanceSession, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, instanceSoulDir, stableSoulId, preparedSoulIdOf, recordedKernelBin, launchConfigsAt, launchPromptPolicyAt, LAUNCH_PROMPT_UPDATE_WARNING, launchReportFor, explicitInstanceName, retireInstance, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, withSafeTaskPrompt, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
|
|
34
34
|
FAILED_SPAWN_BRANCH_LEFT, RETIRE_DELETE_BRANCH_REFUSED,
|
|
35
35
|
} from "../lib/core.mjs";
|
|
36
36
|
import {
|
|
37
|
-
writeFileAtomic, LOCK_FILE, readLock, readLockIfPresent, writeLock, resolvePackages, memoizedRemote,
|
|
37
|
+
writeFileAtomic, LOCK_FILE, canonicalLock, readLock, readLockIfPresent, writeLock, resolvePackages, memoizedRemote,
|
|
38
38
|
classifyPackageValue, parsePackageRequest } from "../lib/packages.mjs";
|
|
39
39
|
import { loadLocal, validateWorkspace, validateLocal, discoverPackageSouls, workspaceWarnings, memberRowByKey } from "../lib/workspace.mjs";
|
|
40
40
|
import { discoveredTeamKeys, isTeamRefusal, localTeamsClosedProblem, recordedTeams, reportRows, soulKeyOf, soulTeams, teamKeyOf, teamModel } from "../lib/teams.mjs";
|
|
@@ -252,6 +252,40 @@ function doctorLocalTeams(local) {
|
|
|
252
252
|
information: !standalone && file === null && declared ? ["local-teams-closed: whether oats-workspace.yaml allows oats-local.yaml teams/defaultTeam (localTeams: true) couldn't be checked: this deployment hasn't observed its workspace yet; run oats sync"] : [] };
|
|
253
253
|
}
|
|
254
254
|
|
|
255
|
+
/** Operator coverage in doctor (#671), OFFLINE like the rest of doctor: the souls this workspace offers,
|
|
256
|
+
* discovered and resolved from this machine's cache only (cacheOnlyRemote: no git process, no network),
|
|
257
|
+
* for the workspace and EVERY declared team. Warnings in problems; when the cache cannot answer, one
|
|
258
|
+
* information line that says coverage is unknown, never that the operator is missing.
|
|
259
|
+
* → { problems: [{ code, message, remedy, label? }], information: [string] } */
|
|
260
|
+
async function doctorOperator(ws) {
|
|
261
|
+
const { operatorCoverage, operatorProblems, cacheOnlyRemote } = await import("../lib/operator-coverage.mjs");
|
|
262
|
+
const { discoverOrStandalone } = await import("../lib/instance-resolution.mjs");
|
|
263
|
+
const deployment = dirname(ws.local.path);
|
|
264
|
+
const local = ws.local.value;
|
|
265
|
+
const remote = cacheOnlyRemote();
|
|
266
|
+
const remoteOptions = remoteOptionsFromEnv();
|
|
267
|
+
// Doctor reads the resolutions `oats souls` (and readiness, spawn) leave in the cache; `oats sync` alone
|
|
268
|
+
// does not resolve souls. Online, `oats readiness --soul <soul>` answers the same question.
|
|
269
|
+
const CACHE_REMEDY = "oats sync, then oats souls (it resolves every soul; doctor reads what that keeps), or online: oats readiness --soul <soul>";
|
|
270
|
+
let coverage, workspace = null, unknownRemedy = CACHE_REMEDY;
|
|
271
|
+
try {
|
|
272
|
+
const lock = readLockIfPresent(deployment);
|
|
273
|
+
const discovery = await discoverOrStandalone(local, { lock, deployment, remoteOptions, remote });
|
|
274
|
+
workspace = discovery.workspace?.name ?? null;
|
|
275
|
+
const labels = [...teamModel(discovery.standalone === true ? null : discovery.workspace, local, { workspaceKey: discovery.key ?? null }).labels.keys()].sort();
|
|
276
|
+
coverage = await operatorCoverage({ discovery, local, lock, teams: labels, remoteOptions, remote });
|
|
277
|
+
} catch (e) {
|
|
278
|
+
// A cache miss is the cache's; anything else (an invalid lock, which doctor reports above) is named as itself.
|
|
279
|
+
const missed = e?.code === "E_REMOTE_UNREADABLE";
|
|
280
|
+
coverage = { known: false, reason: missed ? `this machine's cache cannot answer (${e.message})` : `${e?.code ? `${e.code}: ` : ""}${e?.message ?? e}` };
|
|
281
|
+
if (!missed) unknownRemedy = "fix the error named here (doctor reports it), then run doctor again";
|
|
282
|
+
}
|
|
283
|
+
const found = operatorProblems(coverage, { workspace, unknownRemedy });
|
|
284
|
+
const unknown = found.find((p) => p.code === "operator-coverage-unknown");
|
|
285
|
+
if (unknown) return { problems: [], information: [`${unknown.code}: ${unknown.message}; ${unknown.remedy}`] };
|
|
286
|
+
return { problems: found.map(({ code, label, message, remedy }) => ({ code, ...(label ? { label } : {}), message, remedy })), information: [] };
|
|
287
|
+
}
|
|
288
|
+
|
|
255
289
|
/** Workspace-model v2 doctor data, OFFLINE: the deployment declaration found
|
|
256
290
|
* walking up from ctx (oats-local.yaml) and the lock v3 beside it. Doctor never
|
|
257
291
|
* goes to the network for this view (only `--soul`, which resolves the soul like a
|
|
@@ -619,12 +653,13 @@ async function doctorWorkspaceJson(ctx, soulName, ws) {
|
|
|
619
653
|
const agentsRoot = join(dirname(ws.local.path), "agents");
|
|
620
654
|
const localTeams = doctorLocalTeams(ws.local.value);
|
|
621
655
|
const schedules = unresolvedScheduleAttempts(dirname(ws.local.path));
|
|
622
|
-
const
|
|
656
|
+
const operator = await doctorOperator(ws);
|
|
657
|
+
const problems = [...legacyLayoutProblems(agentsRoot), readableInstanceHomes(agentsRoot), ...localTeams.problems, ...schedules.problems, ...operator.problems].filter(Boolean);
|
|
623
658
|
return {
|
|
624
659
|
schemaVersion: 1, workspaceApi: 2, context: ctx,
|
|
625
660
|
workspace: { file: ws.local.path, ref: ws.local.workspace },
|
|
626
661
|
workspaceError: ws.localError, lockFile: ws.lockFile, packages: ws.packages, lockError: ws.lockError,
|
|
627
|
-
information: [...(operationalKnowledgeNote(composition, soulName) ? [operationalKnowledgeNote(composition, soulName)] : []), ...localTeams.information, ...schedules.information],
|
|
662
|
+
information: [...(operationalKnowledgeNote(composition, soulName) ? [operationalKnowledgeNote(composition, soulName)] : []), ...localTeams.information, ...schedules.information, ...operator.information],
|
|
628
663
|
composedInstructions: composition?.text, instructionBlocks: composition?.blocks,
|
|
629
664
|
...(problems.length ? { problems } : {}),
|
|
630
665
|
};
|
|
@@ -664,7 +699,9 @@ async function doctor(dir) {
|
|
|
664
699
|
for (const p of localTeams.problems) console.log(`\n! ${p.code} (${p.condition}): ${p.message}`);
|
|
665
700
|
const schedules = unresolvedScheduleAttempts(dirname(ws.local.path));
|
|
666
701
|
for (const p of schedules.problems) console.log(`\n! ${p.code}: ${p.message}`);
|
|
667
|
-
|
|
702
|
+
const operator = await doctorOperator(ws);
|
|
703
|
+
for (const p of operator.problems) console.log(`\n! ${p.code}: ${p.message}\n ${p.remedy}`);
|
|
704
|
+
for (const line of [...localTeams.information, ...schedules.information, ...operator.information]) console.log(`\nINFO: ${line}`);
|
|
668
705
|
if (soulName) {
|
|
669
706
|
const information = operationalKnowledgeNote(composition, soulName);
|
|
670
707
|
if (information) console.log(`\nINFO: ${information}`);
|
|
@@ -815,7 +852,8 @@ function launchPreview(bail) {
|
|
|
815
852
|
// selection the planner refuses it (E_LAUNCH_LEGACY: re-spawn it from the deployment).
|
|
816
853
|
let d, frozen;
|
|
817
854
|
try { frozen = withSafeTaskPrompt(meta.command, meta.harness); d = describeLaunchCommand(frozen); } catch (e) { bail(e.code || "E_LAUNCH_COMMAND_UNSUPPORTED", e.message); }
|
|
818
|
-
|
|
855
|
+
const launchPromptAnswers = launchPromptPolicyAt(dirname(dirname(dirname(dirname(home)))), home);
|
|
856
|
+
jsonOk({ context, selected, launchPromptAnswers, ...(launchPromptAnswers.awebDevelopmentChannel ? { warnings: [LAUNCH_PROMPT_UPDATE_WARNING] } : {}), selection: { source: "frozen-command", launchConfig: null, harness: null, model: null, yolo: null }, harness: meta.harness, model: meta.model || null, modelSource: meta.model ? "recorded" : "native default", yolo: meta.yolo ?? null, launchConfig: null, launchConfigSource: null, launchConfigDefault: false, executable: { path: d.executable, declared: null, resolvedFrom: "recorded" }, argv: d.argv, environment: d.environment, command: redactLaunchCommand(frozen), prompt: { kind: "task-file", file: "TASK.md" }, hooks: null, preflight: [{ check: "recipe", ok: true, detail: "frozen command; a selection is refused (E_LAUNCH_LEGACY): re-spawn it" }], ok: true });
|
|
819
857
|
return;
|
|
820
858
|
}
|
|
821
859
|
const agentsRoot = agentsRootOfHome(home);
|
|
@@ -837,7 +875,7 @@ function launchPreview(bail) {
|
|
|
837
875
|
const command = renderLaunchRecipe(recipe, { home, instance, redact: true, trustHome: plan.trustHome });
|
|
838
876
|
const d = describeLaunchCommand(command);
|
|
839
877
|
const environment = d.environment.map((e) => e.reference && recipe.env[e.name]?.fromEnv ? { name: e.name, fromEnv: recipe.env[e.name].fromEnv } : e);
|
|
840
|
-
jsonOk({ context, selected, selection: { source: plan.selectionSource, launchConfig: recipe.launchConfig, harness: sel.harness ?? null, model: sel.model ?? null, yolo: sel.yolo ?? null }, harness: plan.harness, model: recipe.model, modelSource: plan.modelSource, yolo: recipe.yolo ?? null, launchConfig: recipe.launchConfig, launchConfigSource: recipe.launchConfigSource, launchConfigDefault: recipe.launchConfigDefault === true, executable: { path: plan.executable.path, declared: plan.executable.declared ?? null, resolvedFrom: plan.executable.resolvedFrom }, argv: d.argv, environment, command, prompt: recipe.prompt, hooks: redactLaunchRecipe(recipe).hooks, preflight: plan.preflight, ok: plan.ok });
|
|
878
|
+
jsonOk({ context, selected, launchPromptAnswers: plan.launchPromptAnswers, ...(plan.warnings?.length ? { warnings: plan.warnings } : {}), selection: { source: plan.selectionSource, launchConfig: recipe.launchConfig, harness: sel.harness ?? null, model: sel.model ?? null, yolo: sel.yolo ?? null }, harness: plan.harness, model: recipe.model, modelSource: plan.modelSource, yolo: recipe.yolo ?? null, launchConfig: recipe.launchConfig, launchConfigSource: recipe.launchConfigSource, launchConfigDefault: recipe.launchConfigDefault === true, executable: { path: plan.executable.path, declared: plan.executable.declared ?? null, resolvedFrom: plan.executable.resolvedFrom }, argv: d.argv, environment, command, prompt: recipe.prompt, hooks: redactLaunchRecipe(recipe).hooks, preflight: plan.preflight, ok: plan.ok });
|
|
841
879
|
}
|
|
842
880
|
async function launchConfigCmd() {
|
|
843
881
|
const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
|
|
@@ -1312,8 +1350,10 @@ const APPROVAL_REMOVED = "package approval was removed; declaring a package in p
|
|
|
1312
1350
|
* `packages:` against the lock (commit + integrity), write the lock. There is no approval step:
|
|
1313
1351
|
* declaring a package in `packages:` is the trust decision (human decision 2026-09-24).
|
|
1314
1352
|
* `bail` never returns (it exits the process with the caller's error shape).
|
|
1353
|
+
* `plan` (#731, `oats sync --plan`): the same discovery, resolution and report, written nowhere —
|
|
1354
|
+
* no lock, no agents/, no automations snapshot; `lockFile` is the lock a sync would write.
|
|
1315
1355
|
* → { report, lock, discovery, items, lockFile, problems } */
|
|
1316
|
-
async function performSync(ctx, bail, { onDiscovered } = {}) {
|
|
1356
|
+
async function performSync(ctx, bail, { onDiscovered, plan = false } = {}) {
|
|
1317
1357
|
if (args.includes("--approve")) return bail("E_BAD_ARGS", `--approve: ${APPROVAL_REMOVED}`, { flag: "--approve" });
|
|
1318
1358
|
const catalog = catalogForSync(bail);
|
|
1319
1359
|
const discovery = await discoverForCli(ctx, bail);
|
|
@@ -1333,8 +1373,9 @@ async function performSync(ctx, bail, { onDiscovered } = {}) {
|
|
|
1333
1373
|
throw e;
|
|
1334
1374
|
}
|
|
1335
1375
|
const lock = resolved.lock;
|
|
1336
|
-
let lockFile;
|
|
1337
|
-
|
|
1376
|
+
let lockFile = join(resolve(ctx.deploymentDir), LOCK_FILE);
|
|
1377
|
+
// A plan validates the lock exactly as writeLock would (canonicalLock), so it never answers ok where the sync fails.
|
|
1378
|
+
try { if (plan) canonicalLock(lock); else lockFile = writeLock(ctx.deploymentDir, lock); } catch (e) { return bail(e.code || "E_LOCK_SCHEMA", e.message, e.details); }
|
|
1338
1379
|
// Package souls come from the lock: list what THIS sync locked, not what the previous lock held.
|
|
1339
1380
|
if (discovery.standalone !== true) {
|
|
1340
1381
|
let pkg;
|
|
@@ -1348,19 +1389,22 @@ async function performSync(ctx, bail, { onDiscovered } = {}) {
|
|
|
1348
1389
|
}
|
|
1349
1390
|
// The deployment's instance root: <deployment>/agents/ (findRoot's marker). A hand-written
|
|
1350
1391
|
// oats-local.yaml + sync is a complete deployment; spawn must not answer E_NO_DEPLOYMENT after it.
|
|
1351
|
-
|
|
1392
|
+
// A plan creates nothing: on a deployment that never synced, a schedule whose cwd is under agents/ is reported
|
|
1393
|
+
// invalid by the plan and accepted by the sync that creates agents/ first (#731 review, accepted edge).
|
|
1394
|
+
if (!plan) try { mkdirSync(join(ctx.deploymentDir, "agents"), { recursive: true }); } catch { /* reported by spawn's E_NO_DEPLOYMENT remedy if it matters */ }
|
|
1352
1395
|
// Workspace automations (0.29.0): discovered with the members and the new lock (a trigger
|
|
1353
1396
|
// template instantiates at the locked package commit), kept as the snapshot the host tick reads.
|
|
1354
1397
|
let automations;
|
|
1355
|
-
try { automations = await takeAutomationSnapshot(ctx, discovery, lock); }
|
|
1398
|
+
try { automations = await takeAutomationSnapshot(ctx, discovery, lock, { write: !plan }); }
|
|
1356
1399
|
catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) return bail(e.code, e.message, e.details); throw e; }
|
|
1357
1400
|
problems.push(...automations.problems);
|
|
1358
1401
|
const members = memberRows(discovery);
|
|
1359
1402
|
const packages = packageRows(lock);
|
|
1360
1403
|
const changes = resolved.changes;
|
|
1361
1404
|
const items = workspaceItems(discovery, lock, ctx.local, ctx.deploymentDir);
|
|
1362
|
-
const
|
|
1363
|
-
|
|
1405
|
+
const snapshotDue = plan && automationSnapshotDue(ctx.deploymentDir, automations);
|
|
1406
|
+
const report = { syncApi: 1, ...(plan ? { plan: true } : {}), automations: automationCounts(automations), standalone: discovery.standalone === true || undefined, workspace: { name: workspaceName(discovery), key: discovery.key, url: discovery.url, commit: discovery.commit, observedAt: discovery.observedAt, local: ctx.localPath, lock: lockFile }, members, packages, changes, problems, warnings: discovery.warnings ?? [] };
|
|
1407
|
+
return { report, lock, discovery, items, lockFile, problems, snapshotDue };
|
|
1364
1408
|
}
|
|
1365
1409
|
|
|
1366
1410
|
/** The one-line standalone explanation (decision 10). `standaloneReason` says WHY the view is
|
|
@@ -1386,7 +1430,8 @@ function printSyncReport(ctx, synced) {
|
|
|
1386
1430
|
console.log(`packages ${packages.map((p) => `${p.id} ${p.version} ✓ (@ ${short(p.commit)})`).join(" ") || "(none)"}`);
|
|
1387
1431
|
const changed = changes.filter((c) => c.to !== null && c.from !== c.to).map((c) => `${c.id} ${c.from ?? "—"} → ${c.to} (@ ${short(c.commit)})`);
|
|
1388
1432
|
const removed = changes.filter((c) => c.to === null).map((c) => `${c.id} ${c.from} → removed`);
|
|
1389
|
-
|
|
1433
|
+
const plan = report.plan === true;
|
|
1434
|
+
console.log(`${plan ? "to change " : "changed "} ${[...changed, ...removed].join(" ") || `(nothing — the lock already ${plan ? "describes" : "described"} this workspace)`}`);
|
|
1390
1435
|
const memberSouls = items.souls.filter((s) => s.kind === "member");
|
|
1391
1436
|
const externalSouls = items.souls.filter((s) => s.kind === "external");
|
|
1392
1437
|
// Souls have no private mode (0.26.0); the private count is of repo-owned member capabilities.
|
|
@@ -1400,22 +1445,24 @@ function printSyncReport(ctx, synced) {
|
|
|
1400
1445
|
if (ac.triggers || ac.schedules) console.log(`automations ${ac.triggers} trigger${ac.triggers === 1 ? "" : "s"}, ${ac.schedules} schedule${ac.schedules === 1 ? "" : "s"} in the members (oats trigger list · oats schedule list)`);
|
|
1401
1446
|
for (const p of synced.problems ?? discovery.problems) console.log(`problem ${p.code} ${p.repoKey ? `${memberLabel(p.repoKey)}:` : ""}${p.path} ${p.message}`);
|
|
1402
1447
|
for (const w of discovery.warnings ?? []) console.log(`warning ${w.code} ${w.message}`);
|
|
1403
|
-
console.log(`\
|
|
1448
|
+
if (plan) console.log(`\nplan nothing written: \`oats sync\` would write ${shortPath(lockFile)} ${changes.length ? "with the changes above" : "(unchanged)"}${synced.snapshotDue ? " and the automations snapshot" : ""}`);
|
|
1449
|
+
else console.log(`\nlock ${shortPath(lockFile)}`);
|
|
1404
1450
|
}
|
|
1405
1451
|
|
|
1406
1452
|
/** Discover the workspace automations of a discovery and write the snapshot the host tick reads
|
|
1407
1453
|
* (lib/automations.mjs). A trigger's `from:` instantiates the package template at the lock's
|
|
1408
1454
|
* commit; a schedule is checked against this deployment. → the snapshot */
|
|
1409
|
-
async function takeAutomationSnapshot(ctx, discovery, lock) {
|
|
1455
|
+
async function takeAutomationSnapshot(ctx, discovery, lock, { write = true } = {}) {
|
|
1410
1456
|
const kinds = await automationKinds(ctx.deploymentDir, lock, ctx.remoteOptions);
|
|
1411
1457
|
const found = await A.discoverAutomations(discovery, { remote: kinds.remote, memberName: memberLabel, kinds: [kinds.trigger, kinds.schedule], previous: A.readSnapshot(ctx.deploymentDir) });
|
|
1412
1458
|
const snap = A.snapshotOf(discovery, found, { souls: A.soulIndexOf(discovery, memberLabel) });
|
|
1413
1459
|
// A workspace with no triggers or schedules leaves nothing behind (onboard creates what the
|
|
1414
1460
|
// kernel needs and nothing else); a snapshot that existed is replaced, so a removal lands.
|
|
1415
|
-
|
|
1416
|
-
if (!empty || A.readSnapshot(ctx.deploymentDir)) A.writeSnapshot(ctx.deploymentDir, snap);
|
|
1461
|
+
if (write && automationSnapshotDue(ctx.deploymentDir, snap)) A.writeSnapshot(ctx.deploymentDir, snap);
|
|
1417
1462
|
return snap;
|
|
1418
1463
|
}
|
|
1464
|
+
/** Whether a sync writes this snapshot: it has entries, or one exists to replace. */
|
|
1465
|
+
const automationSnapshotDue = (dep, snap) => !!(snap.triggers.length || snap.schedules.length || snap.problems.length || A.readSnapshot(dep));
|
|
1419
1466
|
/** The two kinds' descriptors (lib/triggers.mjs triggerKind, lib/schedule.mjs scheduleKind). */
|
|
1420
1467
|
async function automationKinds(dep, lock, remoteOptions) {
|
|
1421
1468
|
const T = await import("../lib/triggers.mjs");
|
|
@@ -1483,11 +1530,33 @@ function setDisabledHereCli(ws, kind, qid, enabled) {
|
|
|
1483
1530
|
return A.setDisabledHere(path, kind, qid, !enabled, { validate: validateLocal });
|
|
1484
1531
|
}
|
|
1485
1532
|
|
|
1486
|
-
|
|
1533
|
+
const SYNC_USAGE = "usage: oats sync [--dir <deployment>] [--plan] [--json]";
|
|
1534
|
+
/** Why `oats sync`'s argv is not a sync, or undefined (#731): an unknown flag or a positional is refused
|
|
1535
|
+
* before anything is read or written, never ignored. `--approve` keeps its own refusal (performSync). */
|
|
1536
|
+
function syncArgvProblem(argv) {
|
|
1537
|
+
let dirs = 0;
|
|
1538
|
+
for (let i = 1; i < argv.length; i++) {
|
|
1539
|
+
const a = argv[i];
|
|
1540
|
+
if (a === "--json" || a === "--plan") continue;
|
|
1541
|
+
if (a === "--dir") {
|
|
1542
|
+
if (dirs++) return { message: `oats sync: give --dir once\n${SYNC_USAGE}`, details: { flag: a } };
|
|
1543
|
+
if (argv[i + 1] !== undefined && !argv[i + 1].startsWith("--")) i++;
|
|
1544
|
+
continue;
|
|
1545
|
+
}
|
|
1546
|
+
if (a === "--approve") return { message: `--approve: ${APPROVAL_REMOVED}`, details: { flag: a } };
|
|
1547
|
+
if (a.startsWith("-")) return { message: `oats sync: unknown flag ${a}\n${SYNC_USAGE}`, details: { flag: a } };
|
|
1548
|
+
return { message: `oats sync: unexpected argument ${JSON.stringify(a)}: sync takes no positional (the deployment is --dir <deployment>)\n${SYNC_USAGE}`, details: { argument: a } };
|
|
1549
|
+
}
|
|
1550
|
+
return undefined;
|
|
1551
|
+
}
|
|
1552
|
+
|
|
1553
|
+
/** `oats sync [--dir] [--plan] [--json]` — contract §6. `--plan` previews: the same report, nothing written. */
|
|
1487
1554
|
async function syncCmd() {
|
|
1488
1555
|
const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
|
|
1556
|
+
const problem = syncArgvProblem(args);
|
|
1557
|
+
if (problem) return bail("E_BAD_ARGS", problem.message, problem.details);
|
|
1489
1558
|
const ctx = workspaceContext(bail);
|
|
1490
|
-
const synced = await performSync(ctx, bail);
|
|
1559
|
+
const synced = await performSync(ctx, bail, { plan: args.includes("--plan") });
|
|
1491
1560
|
// One envelope (or the §8 report); success is exit 0 (a failure bails with its code).
|
|
1492
1561
|
if (JSON_MODE) jsonOk(synced.report); else printSyncReport(ctx, synced);
|
|
1493
1562
|
}
|
|
@@ -4092,13 +4161,15 @@ Usage:
|
|
|
4092
4161
|
--soul shows final composed AGENTS.md
|
|
4093
4162
|
oats update [--check] [--yes] check npm for a newer kernel+pi bridge and
|
|
4094
4163
|
optionally run the update; then run oats doctor
|
|
4095
|
-
oats sync [--dir <d>] [--json]
|
|
4164
|
+
oats sync [--dir <d>] [--plan] [--json] workspace model v2: observe the workspace named by
|
|
4096
4165
|
oats-local.yaml over its Git remote, confirm every
|
|
4097
4166
|
member (reciprocal oats-membership.yaml), resolve
|
|
4098
4167
|
packages: to exact commits + integrity, write
|
|
4099
|
-
oats-lock.json (v3) and report the diff.
|
|
4100
|
-
|
|
4101
|
-
|
|
4168
|
+
oats-lock.json (v3) and report the diff. --plan:
|
|
4169
|
+
the same report, nothing written (what a bare sync
|
|
4170
|
+
would change). No approval step: declaring a
|
|
4171
|
+
package in packages: is the trust decision
|
|
4172
|
+
(--approve is E_BAD_ARGS)
|
|
4102
4173
|
oats package add <id> <version|git:<repo>@<ref>> edit packages: in oats-workspace.yaml when the
|
|
4103
4174
|
| remove <id> [--dir <d>] workspace repo is the current checkout; otherwise
|
|
4104
4175
|
print the line to add (the file travels through Git)
|
package/docs/capabilities.md
CHANGED
|
@@ -953,7 +953,13 @@ passed as arguments; no shell is involved.
|
|
|
953
953
|
[Teams in the provider environment](#teams-in-the-provider-environment)),
|
|
954
954
|
`OATS_TEAM_SCOPE`, `OATS_TEAM_NAME`, `OATS_WORKSPACE_NAME` and
|
|
955
955
|
`OATS_WORKSPACE_KEY`;
|
|
956
|
-
- `OATS_AGENT` (the soul
|
|
956
|
+
- `OATS_AGENT` and (0.44.0) `OATS_SOUL_ID`, the soul's name and stable id
|
|
957
|
+
with the values its hooks and dispatched commands get (see
|
|
958
|
+
[Commands and hooks](#commands-and-hooks)). For `--soul` on a package
|
|
959
|
+
soul, `OATS_AGENT` is its agents-root name `<package>--<soul>`
|
|
960
|
+
([Package souls](packages.md#package-souls)), as its hooks get it (before
|
|
961
|
+
0.44.0, the bare soul name). A check that relies on them declares
|
|
962
|
+
`compatibility.oats: ">=0.44.0"`;
|
|
957
963
|
- `OATS_SOUL`, the soul directory: a home's recorded one, or for a soul
|
|
958
964
|
(`readiness --soul`, `inspect --soul`) its copy at the resolved commit,
|
|
959
965
|
which the kernel materialises first as a spawn would (0.30; a copy that
|
package/docs/configuration.md
CHANGED
|
@@ -60,6 +60,7 @@ refused (`E_WORKSPACE_SCHEMA`).
|
|
|
60
60
|
| `workspace` | Repo ref of the workspace host (`git:host/org/repo`, `https://…`, `git@host:…`, `file:///…`, `/abs/bare.git`). Read with your own Git credentials; it need not be cloned. |
|
|
61
61
|
| `standalone` | A repo ref to realize on its own: its souls and `from: here` capabilities plus `oats.core`, with no workspace lookup. For a repository whose workspace this machine cannot read ([workspaces.md](workspaces.md#the-standalone-case)). |
|
|
62
62
|
| `clones` | `<repo key>: <absolute path>` for a member clone that is not at `<deployment>/<member name>/`. Only a soul whose work target needs a clone (`work: worktree \| checkout`) uses it. Lookup order: `spawn --repo`, then this map, then `<deployment>/<member name>` (a member named `agents` → `<deployment>/agents-repo`). None → `E_CLONE_MISSING`; a directory whose `origin` is another repository → `E_CLONE_MISMATCH`. |
|
|
63
|
+
| `launchPromptAnswers.homes.<absolute-home>` | Explicit per-home `awebDevelopmentChannel` boolean consent; defaults false. See [launch prompt consent](#exact-home-launch-prompt-consent). |
|
|
63
64
|
| `settings.<cap>.<key>` | Host-owned values a capability's manifest asks for: absolute paths, state roots, delivery modes. The workspace file refuses absolute paths; they go here. Merged into the capability's provider payload after the soul's own and before any `--provider` flag ([three homes](workspaces.md#provider-payloads-have-three-homes)). |
|
|
64
65
|
| `teams.<label>` | A **local** team: `{ team: <provider team id>, description? }`, a team only this deployment uses; every soul may join it. Allowed only where `oats-workspace.yaml` says `localTeams: true` (or in the standalone view); otherwise refused (`E_WORKSPACE_SCHEMA`, reason `local-teams-closed`). Shared teams are committed in `oats-workspace.yaml`; a label in both is `team-label-collision` (the shared one wins). Written by `oats teams add <label> --team <id>` and `oats teams remove <label>`. |
|
|
65
66
|
| `defaultTeam` | This deployment's default team: a label of a local or shared team, under the same condition as `teams`. A soul's own default in the workspace's `souls:` wins over it; it wins over the workspace's `defaultTeam`. The first `oats teams add` sets it; `oats teams default <label>` changes it. |
|
|
@@ -77,6 +78,70 @@ Which teams a soul may join, and its default, are committed in the workspace's
|
|
|
77
78
|
commit instead). How teams are resolved, and what a messaging provider does
|
|
78
79
|
with them, is in [workspaces.md](workspaces.md#teams).
|
|
79
80
|
|
|
81
|
+
## Exact-home launch prompt consent
|
|
82
|
+
|
|
83
|
+
`launchPromptAnswers` belongs only in the host's `oats-local.yaml`. It is
|
|
84
|
+
refused in workspace and soul declarations. Add an entry only for a home whose
|
|
85
|
+
owner has explicitly authorized Claude's aweb development-channel confirmation:
|
|
86
|
+
|
|
87
|
+
```yaml
|
|
88
|
+
launchPromptAnswers:
|
|
89
|
+
homes:
|
|
90
|
+
/absolute/canonical/instance/home:
|
|
91
|
+
awebDevelopmentChannel: false
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
`awebDevelopmentChannel` is a strict boolean; absent means `false`. Unknown keys
|
|
95
|
+
are refused. `workspaceTrust` is unsupported: remove it and handle folder trust
|
|
96
|
+
with the harness. Folder-trust automation is separate work in
|
|
97
|
+
[oats#712](https://github.com/awebai/oats/issues/712); it is not enabled here.
|
|
98
|
+
Each home key is an exact absolute canonical path, with no symlink alias,
|
|
99
|
+
wildcard, dot segment, trailing separator, ancestor inheritance or soul-wide
|
|
100
|
+
default. A home not yet created uses its resolved existing directory ancestor
|
|
101
|
+
plus its intended suffix; launch checks the created home's identity again.
|
|
102
|
+
No existing home is enabled automatically. Removing an entry disables consent
|
|
103
|
+
for future launches.
|
|
104
|
+
|
|
105
|
+
The sole confirmation covered is Claude's development-channel prompt for
|
|
106
|
+
`plugin:aweb-channel@awebai-marketplace`. The provider's `claudeChannelMode`
|
|
107
|
+
selects arguments; it does not grant consent. Approved-mode arguments, another
|
|
108
|
+
plugin, multiple plugins or contradictory channel arguments cannot qualify.
|
|
109
|
+
Environment values, spawn flags and saved launch recipes cannot enable consent.
|
|
110
|
+
Existing harness folder-trust configuration remains independent.
|
|
111
|
+
|
|
112
|
+
Preview reports effective `launchPromptAnswers.awebDevelopmentChannel` and
|
|
113
|
+
`consentSource` without terminal capture or input. `--no-launch` never answers.
|
|
114
|
+
The qualified fixture is limited to Claude 2.1.289 on `darwin-arm64`, at terminal
|
|
115
|
+
geometry 110 columns by 35 rows, with executable SHA-256
|
|
116
|
+
`03d66745e3bb69ec727d66023696f3820bc0a00a8a5ba725eb6706d0c67cbe69`.
|
|
117
|
+
The launch must satisfy these guards and the exact complete frame, selection
|
|
118
|
+
and argument checks. Reported version alone is insufficient; another
|
|
119
|
+
executable, platform, geometry or prompt variant does not inherit acceptance.
|
|
120
|
+
The qualified channel frame starts on its accepted option and permits one
|
|
121
|
+
Enter only. Folder-trust and API-key questions remain unexpected and block.
|
|
122
|
+
A qualified normal-output boundary closes observation without asserting readiness.
|
|
123
|
+
|
|
124
|
+
**Qualified completion and limitation:** exact captured banners cover Claude
|
|
125
|
+
2.1.289 on darwin-arm64 at 110x35 with aweb-channel 1.7.11 installed, and the
|
|
126
|
+
original plugin-absent banner. Both name Opus 5.5, API Usage Billing, auto mode
|
|
127
|
+
and medium effort. Only the bounded canonical-home directory line may vary.
|
|
128
|
+
Other model, billing, effort or permission banners remain unqualified: the one
|
|
129
|
+
Enter can be submitted before `E_SPAWN_INCOMPLETE` with
|
|
130
|
+
`launchPrompts.status: blocked`. The submitted answer remains in `answers` and
|
|
131
|
+
the event receipt; the pane may already be active. Inspect the retained target;
|
|
132
|
+
do not automatically retry input or relaunch it. The installed capture used an
|
|
133
|
+
isolated configuration and dummy credentials with runtime network denied. It
|
|
134
|
+
proves bounded UI completion, not live-account admission, connection or native
|
|
135
|
+
receive readiness, and does not establish success for every production setup.
|
|
136
|
+
|
|
137
|
+
When a harness update changes the version-bound prompt frame, opted-in homes
|
|
138
|
+
block again with `blocked: unexpected prompt` until fixtures are refreshed.
|
|
139
|
+
There is no fallback keystroke or broader matching rule. The returned
|
|
140
|
+
`launchPrompts.receipt` identifies the launch-prompt event receipt; the home
|
|
141
|
+
and pane are retained for inspection. See [launch outcomes](execution-targets.md#launch-prompt-outcomes)
|
|
142
|
+
for recovery. Answering a confirmation never establishes harness or messaging
|
|
143
|
+
receive readiness.
|
|
144
|
+
|
|
80
145
|
## Launch configurations
|
|
81
146
|
|
|
82
147
|
An entry has `harness` (`pi` \| `claude` \| `codex`, required), `executable`
|
package/docs/desktop-cli-api.md
CHANGED
|
@@ -447,7 +447,10 @@ oats readiness (--home <abs> | --soul <name> [--dir <d>]) [--policy] --json
|
|
|
447
447
|
- Four checks, each `{status, items}`. An item is `{subject, status,
|
|
448
448
|
required, reason, producer, evidence, remedy}`, plus `capability: {id}` on a
|
|
449
449
|
per-capability item and the keys named below. Statuses are `pass | fail |
|
|
450
|
-
unknown | not-applicable`.
|
|
450
|
+
unknown | not-applicable`. An item's `reason`, `remedy` and kernel
|
|
451
|
+
`problems[].message` are at most 1000 characters (0.44.0). Longer text,
|
|
452
|
+
such as a remote error, is clipped with `…`. A provider's `result` is
|
|
453
|
+
relayed verbatim.
|
|
451
454
|
- A check's status rolls up its required items (any `fail` → `fail`, else any
|
|
452
455
|
`unknown` → `unknown`, else `pass`; `not-applicable` with none required).
|
|
453
456
|
- `summary.ready` is true when every required item passes or is
|
|
@@ -467,6 +470,8 @@ naming `oats sync`; team refusals go under `configured` instead.
|
|
|
467
470
|
**`configured`.** Producer `capability manifest`: each manifest `requires`
|
|
468
471
|
command, `evidence: {command}`, the manifest's `install` hint as remedy.
|
|
469
472
|
Producer `team model`: the soul's [team readiness items](#team-readiness-items).
|
|
473
|
+
Producer `operator coverage` (0.44.0): the workspace's and the soul's teams'
|
|
474
|
+
[operator coverage items](#operator-coverage-items), warnings only.
|
|
470
475
|
|
|
471
476
|
**`member`** (producer `workspace discovery`): the soul's repository is a
|
|
472
477
|
confirmed member (`evidence: {repoKey, workspace, commit}`); `fail` when not
|
|
@@ -672,13 +677,22 @@ same argument, given once). The ref is checked before anything is written.
|
|
|
672
677
|
### `oats sync`
|
|
673
678
|
|
|
674
679
|
```text
|
|
675
|
-
oats sync [--dir <d>] --json
|
|
680
|
+
oats sync [--dir <d>] [--plan] --json
|
|
676
681
|
```
|
|
677
682
|
|
|
678
683
|
Discovers the workspace, confirms membership, resolves `packages:`, writes
|
|
679
684
|
`oats-lock.json` (lockfileVersion 3), takes the automations snapshot and
|
|
680
685
|
reports. It creates `agents/` if missing.
|
|
681
686
|
|
|
687
|
+
`--plan` (0.44.0) previews: the same discovery, resolution and report, with
|
|
688
|
+
`plan: true`, and nothing written (no lock, no `agents/`, no automations
|
|
689
|
+
snapshot; the remote cache fills as any read fills it). `changes[]` is what a
|
|
690
|
+
bare `oats sync` would apply, `workspace.lock` the lock it would write, and
|
|
691
|
+
`automations` counts what it would snapshot. A flag or a positional `sync` does
|
|
692
|
+
not read is refused with `E_BAD_ARGS` (`details: {flag}` or `{argument}`) before
|
|
693
|
+
anything is read or written. A kernel before 0.44.0 ignores `--plan` and
|
|
694
|
+
applies: gate `sync --plan` on `version` 0.44.0 or later, never by trying.
|
|
695
|
+
|
|
682
696
|
```json
|
|
683
697
|
{"syncApi":1,"automations":{"triggers":3,"schedules":2,"problems":1,"takenAt":"2026-09-26T19:58:09.281Z"},
|
|
684
698
|
"workspace":{"name":"acme","key":"github.com/acme/agents","url":"https://github.com/acme/agents.git","commit":"45b86f64…",
|
|
@@ -693,6 +707,7 @@ reports. It creates `agents/` if missing.
|
|
|
693
707
|
"problems":[],"warnings":[]}
|
|
694
708
|
```
|
|
695
709
|
|
|
710
|
+
- `plan`: `true` on a `--plan` answer, absent otherwise.
|
|
696
711
|
- `automations`: counts from the snapshot this sync took.
|
|
697
712
|
- `workspace.name` is `standalone:<repo>` on a standalone view.
|
|
698
713
|
- `members[]`: `status` is `confirmed | not-listed | no-backlink |
|
|
@@ -1098,7 +1113,10 @@ operator guide: [workspaces.md](workspaces.md#teams).
|
|
|
1098
1113
|
home's own record, as always.
|
|
1099
1114
|
- **A soul's key** is its qualified name: `<package>/<soul>`, or
|
|
1100
1115
|
`<member>/<soul>` with the member repository's name (as `souls.disabled`
|
|
1101
|
-
names it). A label matches `[a-z0-9][a-z0-9._-]
|
|
1116
|
+
names it). A label matches `[a-z0-9][a-z0-9._-]*` and is at most 64
|
|
1117
|
+
characters (0.44.0). A longer one is refused: `E_WORKSPACE_SCHEMA` in
|
|
1118
|
+
either file, `E_BAD_ARGS` from `oats teams add`, and `E_TRIGGER_INVALID`
|
|
1119
|
+
(`field: spawn.teams`) in a trigger.
|
|
1102
1120
|
- **Team ids.** A `team` value (in either file, and `oats teams add --team`)
|
|
1103
1121
|
matches `^[A-Za-z0-9][A-Za-z0-9._:@/+-]{0,255}$`: the kernel's safety rule
|
|
1104
1122
|
(never `-`-led, no whitespace or control characters, bounded). Otherwise
|
|
@@ -1324,6 +1342,77 @@ hasn't observed its workspace yet; run oats sync"`. A removed key in
|
|
|
1324
1342
|
`oats-local.yaml` makes doctor answer that refusal, as for any unreadable
|
|
1325
1343
|
local file.
|
|
1326
1344
|
|
|
1345
|
+
<a id="operator-coverage-items"></a>
|
|
1346
|
+
### Operator coverage items
|
|
1347
|
+
|
|
1348
|
+
(0.44.0, [#671](https://github.com/awebai/oats/issues/671)) Every workspace
|
|
1349
|
+
needs an operator: a soul that composes `oats.setup`. A soul the workspace
|
|
1350
|
+
offers **covers** it when all of these hold on this machine:
|
|
1351
|
+
|
|
1352
|
+
- it is a confirmed member's soul, a locked package soul or an external soul;
|
|
1353
|
+
- it is not in `souls.disabled`;
|
|
1354
|
+
- it resolves as a spawn would;
|
|
1355
|
+
- its modules include `oats.setup`;
|
|
1356
|
+
- it empties no layer slot the workspace fills, so it keeps the workspace's
|
|
1357
|
+
core, messaging and knowledge.
|
|
1358
|
+
|
|
1359
|
+
It covers a team when that team is among its resolved teams. Detection is by
|
|
1360
|
+
composition only: a soul's name never counts, and there is no role marker. An
|
|
1361
|
+
eligible soul is not a launched or authorized seat. These are warnings: they
|
|
1362
|
+
never refuse anything, and nothing is spawned.
|
|
1363
|
+
|
|
1364
|
+
`oats readiness` lists them under `checks.configured` with `producer:
|
|
1365
|
+
"operator coverage"`, `required: false`, `code`, `reason` and `remedy`. Team
|
|
1366
|
+
items cover the subject's own teams only.
|
|
1367
|
+
|
|
1368
|
+
| Code | Subject | Status | Keys | When |
|
|
1369
|
+
|---|---|---|---|---|
|
|
1370
|
+
| `operator-soul-missing` | `operator` | `fail` | `evidence.excluded` | no soul the workspace offers composes `oats.setup` |
|
|
1371
|
+
| `operator-team-uncovered` | `team <label>` | `fail` | `label` | no such soul is eligible for one of the subject's teams |
|
|
1372
|
+
| `operator-coverage-unknown` | `operator` | `unknown` | | a question is still open and a source could not be read; it never asserts absence |
|
|
1373
|
+
|
|
1374
|
+
A source could not be read when:
|
|
1375
|
+
|
|
1376
|
+
- the workspace itself could not be read;
|
|
1377
|
+
- only its member view could (an unreadable host);
|
|
1378
|
+
- discovery dropped a member as `cannot-read`;
|
|
1379
|
+
- a soul file or listing could not be read;
|
|
1380
|
+
- a resolution hit `E_REMOTE_UNREADABLE`.
|
|
1381
|
+
|
|
1382
|
+
A covering soul that was found is still reported. Any other refusal belongs to
|
|
1383
|
+
the soul, since a spawn would meet it too, so that soul does not cover.
|
|
1384
|
+
|
|
1385
|
+
`evidence.excluded` lists the souls that cannot cover although they are
|
|
1386
|
+
relevant, each as `{soul, code}`:
|
|
1387
|
+
|
|
1388
|
+
- a soul whose `soul.yaml` names `oats.setup` but that is disabled
|
|
1389
|
+
(`E_SOUL_DISABLED`), ambiguous (`E_SOUL_AMBIGUOUS`) or refused (the
|
|
1390
|
+
resolution's code);
|
|
1391
|
+
- a soul that composes `oats.setup` but empties a slot the workspace fills
|
|
1392
|
+
(`slot-none`, with `slots`).
|
|
1393
|
+
|
|
1394
|
+
Coverage that holds adds no item.
|
|
1395
|
+
|
|
1396
|
+
`oats doctor` stays offline. It resolves the souls from this machine's cache
|
|
1397
|
+
only (no git process, no network) and checks the workspace and **every**
|
|
1398
|
+
declared team. It lists `operator-soul-missing` and `operator-team-uncovered`
|
|
1399
|
+
under `problems[]` as `{code, label?, message, remedy}` (text: `! <code>:
|
|
1400
|
+
<message>`, then the remedy).
|
|
1401
|
+
|
|
1402
|
+
Doctor reads the resolutions that `oats souls`, readiness and spawn keep in the
|
|
1403
|
+
cache. `oats sync` alone does not resolve souls. When the cache cannot answer,
|
|
1404
|
+
doctor adds no problem. Instead it adds one `information[]` line, starting
|
|
1405
|
+
`operator-coverage-unknown:`, whose remedy is `oats sync`, then `oats souls`.
|
|
1406
|
+
The cache cannot answer when:
|
|
1407
|
+
|
|
1408
|
+
- the machine never synced;
|
|
1409
|
+
- the cache was pruned;
|
|
1410
|
+
- a soul was not yet resolved here;
|
|
1411
|
+
- the deployment uses a configured `standalone:` view, whose membership read
|
|
1412
|
+
is not cached. There, ask readiness.
|
|
1413
|
+
|
|
1414
|
+
Any other error, such as an invalid lock, is named as itself.
|
|
1415
|
+
|
|
1327
1416
|
<a id="soul-launch-preferences-feature-launch-preference-oats-0300"></a>
|
|
1328
1417
|
## Launch preferences
|
|
1329
1418
|
|
|
@@ -1460,6 +1549,48 @@ shows the drift as `launch-changed`.
|
|
|
1460
1549
|
No verb writes `souls.launch`; it is plain YAML. A GUI that edits it checks
|
|
1461
1550
|
the result with `oats inspect --soul <name> --json`.
|
|
1462
1551
|
|
|
1552
|
+
## Launch prompt results
|
|
1553
|
+
|
|
1554
|
+
Spawn preview adds `launchPromptAnswers` with the strict effective boolean
|
|
1555
|
+
`awebDevelopmentChannel` and `consentSource` (a config-file
|
|
1556
|
+
JSON pointer or `null`). This is a policy report, not a terminal observation
|
|
1557
|
+
or readiness assertion. Only the aweb development-channel confirmation is
|
|
1558
|
+
covered, restricted to the qualified Claude executable digest, platform and
|
|
1559
|
+
geometry documented under [launch consent](configuration.md#exact-home-launch-prompt-consent).
|
|
1560
|
+
Folder-trust prompts remain unexpected and blocked.
|
|
1561
|
+
|
|
1562
|
+
An observed launch has `launchPrompts: {status, answers, reason, receipt}`.
|
|
1563
|
+
`receipt` carries the actual checked launch-prompt event-write results,
|
|
1564
|
+
including partial log availability; it is not a receive-readiness receipt.
|
|
1565
|
+
The `launch-prompt` event records the launch start and pane/PID identity,
|
|
1566
|
+
consent provenance, signature identifier/digest, action and outcome. Intent is
|
|
1567
|
+
durable before input; submission (`submitted`, `failed`, `uncertain`) and an
|
|
1568
|
+
observed screen transition are distinct. Unexpected raw screen text is never
|
|
1569
|
+
included in the receipt.
|
|
1570
|
+
|
|
1571
|
+
Spawn and start both reuse `E_SPAWN_INCOMPLETE` for retained prompt outcomes,
|
|
1572
|
+
with `launchPrompts.status` set to `blocked` or `incomplete`. Error details
|
|
1573
|
+
preserve `instance`, `home`, `launched:"unknown"`, `unconfirmed:true` and add
|
|
1574
|
+
`retained:true`, `target`,
|
|
1575
|
+
`parentLineageCommitted`, and `launchPrompts`. Unknown prompts report
|
|
1576
|
+
`blocked: unexpected prompt`. An incomplete audit can follow a possible key;
|
|
1577
|
+
clients must not offer automatic key retry. `launched:false` in retained
|
|
1578
|
+
metadata does not mean there is no process or that another harness may be
|
|
1579
|
+
allocated. Use runtime inspection and the existing start/restart lifecycle.
|
|
1580
|
+
Same-key spawn replay cannot convert a blocked outcome to successful spawn.
|
|
1581
|
+
|
|
1582
|
+
`answers` can contain a `submitted` answer even when the final status is
|
|
1583
|
+
`blocked`: the accepted installed-plugin and plugin-absent completion banners
|
|
1584
|
+
pin specific model/billing/effort/permission text. A different normal-looking banner can block after Enter
|
|
1585
|
+
while the actual pane is active. Consumers must preserve that submitted receipt
|
|
1586
|
+
and never translate this outcome into “nothing started” or automatic retry.
|
|
1587
|
+
The [completion limitation](configuration.md#exact-home-launch-prompt-consent)
|
|
1588
|
+
is part of the shipping contract.
|
|
1589
|
+
|
|
1590
|
+
Strict Desktop/pi readers must accept these additive fields and the new event
|
|
1591
|
+
kind before a writer containing them ships. For operator recovery, see
|
|
1592
|
+
[launch prompt outcomes](execution-targets.md#launch-prompt-outcomes).
|
|
1593
|
+
|
|
1463
1594
|
## Spawn
|
|
1464
1595
|
|
|
1465
1596
|
### The preview
|
|
@@ -1702,7 +1833,7 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
|
|
|
1702
1833
|
| `E_INSTANCE_NAME_INVALID`, `E_INSTANCE_NAME_TAKEN` | see above | |
|
|
1703
1834
|
| `E_DECISION_STALE` | `{decision}` | |
|
|
1704
1835
|
| `E_PLACEMENT_TAKEN`, `E_IDEMPOTENCY_CONFLICT` | `{instance, home}` | |
|
|
1705
|
-
| `E_SPAWN_INCOMPLETE` | `{instance, home, launched, unconfirmed: true}` | |
|
|
1836
|
+
| `E_SPAWN_INCOMPLETE` | `{instance, home, launched, unconfirmed: true}`; retained launch-prompt outcomes additionally carry `{retained: true, target, parentLineageCommitted, launchPrompts}` | See [launch prompt results](#launch-prompt-results). |
|
|
1706
1837
|
| `E_LAUNCH_*`, `E_MODEL_UNKNOWN`, `E_UNSUPPORTED_HARNESS` | | the launch selection is refused |
|
|
1707
1838
|
| `E_LAUNCH_SHIM` | | the home's `oats` (`<home>/.oats/bin/oats`) cannot be written; the spawn is rolled back |
|
|
1708
1839
|
| `E_SCHEDULE_INVALID` | | a bad wake (`--wake-json`, `--wake-file`, `--wake-*`) |
|
|
@@ -2761,6 +2892,20 @@ selection flags. See [the start workflow](desktop-instance-start.md).
|
|
|
2761
2892
|
- Restart is one command: the kernel validates the new selection before
|
|
2762
2893
|
stopping, and owns the stop, lock, launch recovery and metadata. Never
|
|
2763
2894
|
restart by retiring and spawning.
|
|
2895
|
+
- Launch recovery (0.44.0). A start keeps its launch receipt in the home
|
|
2896
|
+
until the next start replaces it. The next start **adopts** a receipt only
|
|
2897
|
+
for a start `instance.json` does not record (one whose metadata write
|
|
2898
|
+
failed): it records that target and launches nothing again. A receipt for
|
|
2899
|
+
a start `instance.json` already records, on the target it records, is
|
|
2900
|
+
**completed**, and none of it is recorded again: a newer launch recipe or
|
|
2901
|
+
provider metadata stays. A plain start then answers `E_SESSION_RUNNING`
|
|
2902
|
+
while that target runs, writing nothing and running no hook; a restart, or
|
|
2903
|
+
a start after the target is gone or the harness exited, starts from
|
|
2904
|
+
`instance.json` as it is, and its own receipt replaces the old one. A
|
|
2905
|
+
receipt that names the recorded start on another target is ambiguous:
|
|
2906
|
+
`E_SESSION_UNKNOWN`, the receipt kept, nothing started. The message names
|
|
2907
|
+
that target and the way out: stop it, then `oats session restart`, which
|
|
2908
|
+
goes ahead once that target no longer runs. Never edit or remove a receipt by hand.
|
|
2764
2909
|
- A lost response does not mean the launch failed: check status before a
|
|
2765
2910
|
retry. A remote home's saved route names its execution host.
|
|
2766
2911
|
- Errors: `E_BAD_ARGS`, `E_SESSION_UNKNOWN`, `E_UNSUPPORTED_MODE`,
|