owenloop 0.5.8 → 0.5.9

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.
Files changed (87) hide show
  1. package/CHANGELOG.md +25 -0
  2. package/README.md +4 -2
  3. package/dist/packages/work/src/agent/loop.d.ts +23 -8
  4. package/dist/packages/work/src/agent/loop.js +48 -6
  5. package/dist/packages/work/src/consumed-verifier.js +6 -17
  6. package/dist/packages/work/src/exec/loop.d.ts +1 -1
  7. package/dist/packages/work/src/exec/loop.js +181 -32
  8. package/dist/packages/work/src/exec/receipt.d.ts +7 -7
  9. package/dist/packages/work/src/exec/receipt.js +6 -6
  10. package/dist/packages/work/src/harness/claude.js +100 -0
  11. package/dist/packages/work/src/hub/client.d.ts +19 -4
  12. package/dist/packages/work/src/hub/client.js +7 -3
  13. package/dist/packages/work/src/hub/types.d.ts +84 -0
  14. package/dist/packages/work/src/main.js +1 -0
  15. package/dist/packages/work/src/roles/agent-run.js +19 -22
  16. package/dist/packages/work/src/roles/exec.js +2 -0
  17. package/dist/packages/work/src/roles/settings.js +2 -0
  18. package/dist/packages/work/src/roles/shift.js +14 -2
  19. package/dist/packages/work/src/roles/util.d.ts +1 -0
  20. package/dist/packages/work/src/roles/util.js +10 -0
  21. package/dist/packages/work/src/settings/hub-roster-cache.d.ts +68 -0
  22. package/dist/packages/work/src/settings/hub-roster-cache.js +370 -0
  23. package/dist/packages/work/src/settings/roster.d.ts +84 -0
  24. package/dist/packages/work/src/settings/roster.js +364 -5
  25. package/dist/packages/work/src/settings/serving.d.ts +17 -0
  26. package/dist/packages/work/src/settings/serving.js +79 -0
  27. package/dist/packages/work/src/settings/settings.d.ts +14 -1
  28. package/dist/packages/work/src/settings/settings.js +14 -0
  29. package/dist/packages/work/src/shift/loop.d.ts +108 -5
  30. package/dist/packages/work/src/shift/loop.js +299 -51
  31. package/dist/packages/work/src/shift/protocol.d.ts +7 -5
  32. package/dist/packages/work/src/shift/runtime.d.ts +15 -0
  33. package/dist/packages/work/src/shift/runtime.js +94 -4
  34. package/dist/packages/work/src/shift/server.js +2 -0
  35. package/dist/packages/work/src/shift/spawn.d.ts +17 -2
  36. package/dist/packages/work/src/shift/spawn.js +16 -13
  37. package/dist/packages/work/src/shift/state.d.ts +29 -2
  38. package/dist/packages/work/src/shift/state.js +45 -15
  39. package/dist/packages/work/src/usage.d.ts +1 -1
  40. package/dist/packages/work/src/usage.js +7 -1
  41. package/dist/packages/work/src/util/modifier-init.d.ts +7 -0
  42. package/dist/packages/work/src/util/modifier-init.js +73 -0
  43. package/dist/src/bundle/tar.d.ts +9 -4
  44. package/dist/src/bundle/tar.js +9 -4
  45. package/dist/src/capabilities.d.ts +6 -0
  46. package/dist/src/cli.d.ts +14 -1
  47. package/dist/src/cli.js +687 -75
  48. package/dist/src/config-dir.d.ts +1 -1
  49. package/dist/src/config-dir.js +1 -1
  50. package/dist/src/crypto/index.d.ts +1 -1
  51. package/dist/src/crypto/index.js +1 -1
  52. package/dist/src/crypto/org-root.d.ts +30 -12
  53. package/dist/src/crypto/org-root.js +162 -14
  54. package/dist/src/crypto/records.d.ts +2 -0
  55. package/dist/src/crypto/records.js +2 -0
  56. package/dist/src/defs.d.ts +6 -1
  57. package/dist/src/defs.js +203 -8
  58. package/dist/src/engine.d.ts +42 -7
  59. package/dist/src/engine.js +158 -16
  60. package/dist/src/index.d.ts +4 -4
  61. package/dist/src/index.js +2 -2
  62. package/dist/src/mcp/serve.d.ts +22 -0
  63. package/dist/src/mcp/serve.js +88 -8
  64. package/dist/src/model.d.ts +2 -0
  65. package/dist/src/model.js +32 -25
  66. package/dist/src/order-resolver.d.ts +1 -0
  67. package/dist/src/order-resolver.js +8 -1
  68. package/dist/src/schemas/index.d.ts +11 -0
  69. package/dist/src/schemas/order.v1.schema.json +7 -1
  70. package/dist/src/store.d.ts +5 -0
  71. package/dist/src/store.js +43 -8
  72. package/dist/src/types.d.ts +40 -3
  73. package/docs/authoring.md +90 -2
  74. package/docs/bundles.md +26 -2
  75. package/docs/cli.md +170 -28
  76. package/docs/crypto.md +19 -3
  77. package/docs/design.md +70 -1
  78. package/docs/routing.md +189 -34
  79. package/docs/shift-logs.md +20 -9
  80. package/docs/wire-contracts.md +50 -7
  81. package/examples/workflows/delivery.yaml +31 -14
  82. package/examples/workflows/ship.yaml +10 -2
  83. package/package.json +1 -1
  84. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  85. package/plugins/claude-code/plugin/.mcp.json +1 -1
  86. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  87. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
package/dist/src/cli.js CHANGED
@@ -32,7 +32,7 @@
32
32
  *
33
33
  * Global: --db <path> (env OWENLOOP_DB), --defs <dir> (env OWENLOOP_DEFS).
34
34
  */
35
- import { chmodSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
35
+ import { chmodSync, existsSync, linkSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
36
36
  import { basename, delimiter, dirname, isAbsolute, join, resolve, sep } from 'node:path';
37
37
  import { spawn, spawnSync } from 'node:child_process';
38
38
  import { createServer } from 'node:http';
@@ -49,13 +49,13 @@ import { CliError, dbPathRefusingSymlink, detId, mkdirRefusingSymlink, nowMs, pa
49
49
  import { packageVersion } from "./package-version.js";
50
50
  import { authHeader, deleteCredential, discoverMetadata, ensureFreshOAuth, hubFetch, hubMaxResponseBytes, mintAgentCredential, readBodyBounded, refreshOAuth, rekeyAgentCredential, storeCredential, } from "./credentials.js";
51
51
  import { PrincipalKeyManager } from "./crypto/keys.js";
52
- import { createHash } from 'node:crypto';
52
+ import { createHash, randomUUID } from 'node:crypto';
53
53
  import { DSSE_SSH_NAMESPACE, decodeBase64Strict, dsseSignEnrollmentGrant, dsseSignOrigin, dsseSignPublication, dsseSignRevocation, PAYLOAD_TYPE_ORIGIN, PAYLOAD_TYPE_PUBLICATION, } from "./crypto/dsse.js";
54
54
  import { assertEd25519PubText, createSshSigner, SshSignerError } from "./crypto/ssh.js";
55
55
  import { publicKeyDescriptor } from "./crypto/keys.js";
56
56
  import { DEFAULT_MACHINE_SCOPE, buildEnrollmentGrant, verifyRosterEntry } from "./crypto/enrollment.js";
57
57
  import { resolveAllowedSigners } from "./crypto/trust-roots.js";
58
- import { orgRootPrivateKeyPath, orgRootPublicKeyPath, resolveOrgRoot, revocationsDir, rosterDir, } from "./crypto/org-root.js";
58
+ import { orgRootPrivateKeyPath, orgRootPublicKeyPath, resolveOrgRoot, revocationsDir, assertNoStrandedLegacyGrants, grantsDir, } from "./crypto/org-root.js";
59
59
  import { runMcpCommand } from "./mcp/serve.js";
60
60
  import { DEFAULT_TAR_LIMITS, extractTarGz } from "./untar.js";
61
61
  import { BundleError, digestBundle, inspectBundle, packBundle, unpackBundle } from "./bundle/index.js";
@@ -63,7 +63,8 @@ import { acquireInstallLock, ADD_JOURNAL_FILENAME, archivePathViolation, commitI
63
63
  import { BundleIngestorUnavailableError, globalStoreRoot, installWorkflowBundle, inspectCasDefs, loadCasDefs, PreCommitVerifierUnavailableError, projectStoreRoot, createBundleIngestor, createPreCommitVerifier, recoverWorkflowStore, storeIndexPath, workflowStoreReplacementRecovery, workflowStoreStatePaths, } from "./store/index.js";
64
64
  import { asAgentIdentities, asCreateWorkflowOk, asCapabilityRerouteAdded, asCapabilityRerouteRemoved, asCapabilityReroutes, asCapabilityRouteAdded, asCapabilityRouteRemoved, asCapabilityRoutes, asCrewCreated, asCrewDeleted, asCrewMemberAdded, asCrewMemberRemoved, asCrews, asRoutingAlerts, asRunRouting, asWhoami, computeServerDiff, credentialBackend, createWorkflowError, credentialFilePath, credentialSlot, DEFAULT_HUB, externalCredentialCommand, hashDefForHub, hubBindingPath, keychainServiceFor, listStoredHubOrigins, normalizeOrigin, parseWorkflowList, pkcePair, randomState, readCredentialFile, readHubBinding, readStoredCredential, resolveEndpoint, resolveKeychain, writeCredentialFile, writeHubBinding, } from "./hub.js";
65
65
  import { loadSettings, settingsPath as executionSettingsPath } from "../packages/work/src/settings/settings.js";
66
- import { machineRosterLayers, mergeRosterLayers } from "../packages/work/src/settings/roster.js";
66
+ import { discoverCrewRosterFiles, crewRosterPath, effectiveRosterLayers, explainRosterShadows, mergeRosterLayers } from "../packages/work/src/settings/roster.js";
67
+ import { readHubRosterCache, syncHubRosterCache } from "../packages/work/src/settings/hub-roster-cache.js";
67
68
  import { adapterFor } from "../packages/work/src/harness/registry.js";
68
69
  import "../packages/work/src/harnesses.js";
69
70
  import { owenloopConfigDir } from "./config-dir.js";
@@ -961,6 +962,12 @@ async function dispatchTrust(io, args) {
961
962
  throw new CliError(`owenloop trust grant: ${error instanceof Error ? error.message : String(error)}`);
962
963
  }
963
964
  const signer = signingKeyInfo(io, signingPath);
965
+ try {
966
+ assertNoStrandedLegacyGrants(io.env);
967
+ }
968
+ catch (error) {
969
+ throw new CliError(`owenloop trust grant: ${error instanceof Error ? error.message : String(error)}`);
970
+ }
964
971
  const record = {
965
972
  newKey: {
966
973
  keyid: newKey.keyid,
@@ -976,7 +983,7 @@ async function dispatchTrust(io, args) {
976
983
  const sshSigner = createSshSigner({ namespace: DSSE_SSH_NAMESPACE, signKeyPath: signer.path });
977
984
  try {
978
985
  const signed = await dsseSignEnrollmentGrant(Buffer.from(canonicalJsonBytes(record)), sshSigner);
979
- const output = trustEnvelopeOutput(args, io.cwd, join(rosterDir(io.env), `${trustKeyHash(newKey.keyid)}.grant.dsse`));
986
+ const output = trustEnvelopeOutput(args, io.cwd, join(grantsDir(io.env), `${trustKeyHash(newKey.keyid)}.grant.dsse`));
980
987
  writeTrustEnvelope(output, signed.envelope);
981
988
  print(io, { ok: true, path: output, keyid: newKey.keyid, grantedBy: signer.keyid, principal, validFrom: record.validFrom });
982
989
  }
@@ -1124,11 +1131,14 @@ Commands:
1124
1131
  push [<defName>...] [--bundle <bundle.wnlp>] [--force] [--dry-run] [--hub <origin>] [--as <slot>]
1125
1132
  publish local workflow defs, or exact bundle-backed defs, to the safely resolved hub (server-diffed, idempotent)
1126
1133
  --as names the credential slot: human (default), agent, or agent:<account>
1127
- start <defName> [--provide name=json ...] [--crew <name>] [--title <text>] [--modifier <name>] [--hub <url>]
1134
+ start <defName> [--provide name=json ...] [--crew <name>] [--title <text>] [--modifier <name>] [--scope <label>] [--priority <low|normal|high>] [--hub <url>]
1128
1135
  ${' '.repeat(41)}start a published workflow on the bound hub (human credential)
1129
1136
  ${' '.repeat(41)}--modifier names one value from the def's declared \`modifiers:\` set; every
1130
1137
  ${' '.repeat(41)}step's capability is then offered as \`<capability>:<modifier>\`. Omit it and
1131
1138
  ${' '.repeat(41)}the run carries no modifier and its steps are offered on BARE capabilities.
1139
+ ${' '.repeat(41)}--scope is a free routing label recorded on the run — no registry, no fixed set.
1140
+ ${' '.repeat(41)}Omit it and the run is routed by the org's routes alone.
1141
+ ${' '.repeat(41)}--priority is one of low, normal, high. Omit it and the hub applies normal.
1132
1142
  cancel <workflow> [--reason <text>] [--hub <url>]
1133
1143
  ${' '.repeat(41)}cancel a running instance on the bound hub (human credential; agents cannot cancel).
1134
1144
  ${' '.repeat(41)}Closes every open lease so the run stops being re-offered, and records the
@@ -1159,7 +1169,17 @@ ${' '.repeat(41)}and escalations. Unrelated to the local \`show\`, which reads a
1159
1169
  crew member rm <crewId> <principalId> [--hub <url>] remove a principal from a crew
1160
1170
  setup [--hub <url>] [--new-agent <name> | --replace-agent <name>] [--crews <a,b>] [--scopes <a,b>] [--reuse-ssh-key <path>] converge this machine's install: human login, agent credential, signing keys, owenloop settings, plugins (idempotent)
1161
1171
  doctor [--hub <url>] check this machine's owenloop install and report each piece (read-only)
1162
- roster show [crew] print a merged crew roster and its layer provenance (read-only)
1172
+ roster show [crew] print the offline four-layer roster cascade and provenance
1173
+ roster org [--hub <url>] read the live hub org-global and per-crew rosters (human credential)
1174
+ roster org put <capability> --candidate <harness>:<model>:<effort> [--crew <name>] [--hub <url>]
1175
+ ${' '.repeat(41)}replace one hub roster row (human admin credential)
1176
+ roster org rm <capability> [--crew <name>] [--hub <url>]
1177
+ ${' '.repeat(41)}remove one hub roster row (human admin credential)
1178
+ roster registry [--hub <url>] list hub harnesses, models, and supported efforts (human credential)
1179
+ roster registry put <harness> [--model <model>:<effort,effort…>]… [--display-name <text>] [--hub <url>]
1180
+ ${' '.repeat(41)}replace a harness's hub model snapshot (human admin credential)
1181
+ roster sync [--hub <url>] [--as agent|agent:<account>]
1182
+ ${' '.repeat(41)}refresh the local hub-rosters cache with an agent credential
1163
1183
  enrollments [--hub <url>] list the hub's relayed machine enrollment grants (read-only)
1164
1184
  mcp [--hub <url>] serve the hub control plane over stdio MCP (spawned by MCP hosts, not run by humans)
1165
1185
  work <subcommand> [args] run execution-side shift/hold/exec/agent-run/... commands
@@ -1187,7 +1207,7 @@ ${' '.repeat(41)}and escalations. Unrelated to the local \`show\`, which reads a
1187
1207
  reject <wf> <path> --by <author> --text <msg>
1188
1208
  retract <wf> <path> --by <author> --text <msg>
1189
1209
  skip <wf> <path> --by <author> --text <msg>
1190
- retry <wf> <path> [--by <author>] [--text <guidance>] clear a §6 stall, or ANSWER an ask
1210
+ retry <wf> <path> [--by <author>] [--text <guidance>] [--hub <url>] clear a §6 stall, or ANSWER an ask
1191
1211
  ask <wf> <path> <question> [--by <author>] hold an owed artifact on a question for a human
1192
1212
  inbox every held question across all instances, with its answer command
1193
1213
  heartbeat <wf> <run> [--now <ms>] touch liveness timestamp on an open run
@@ -1239,7 +1259,7 @@ export const COMMAND_OPTIONS = new Map([
1239
1259
  ['publish', cmdOpts('unsigned', 'output', 'source', 'hub')],
1240
1260
  ['trust', cmdOpts('force', 'key', 'principal', 'pools', 'labels', 'namespaces', 'delegate', 'signing-key', 'output', 'reason', 'effective-from')],
1241
1261
  ['push', cmdOpts('dry-run', 'force', 'hub', 'as', 'bundle')],
1242
- ['start', cmdOpts('hub', 'crew', 'title', 'provide', 'modifier')],
1262
+ ['start', cmdOpts('hub', 'crew', 'title', 'provide', 'modifier', 'scope', 'priority')],
1243
1263
  ['cancel', cmdOpts('hub', 'reason')],
1244
1264
  ['instance', cmdOpts('hub')],
1245
1265
  ['agent', cmdOpts('crews', 'hub', 'scopes', 'shift')],
@@ -1252,7 +1272,7 @@ export const COMMAND_OPTIONS = new Map([
1252
1272
  ['crew', cmdOpts('hub', 'kind', 'owner')],
1253
1273
  ['setup', cmdOpts('hub', 'new-agent', 'replace-agent', 'crews', 'scopes', 'reuse-ssh-key')],
1254
1274
  ['doctor', cmdOpts('hub')],
1255
- ['roster', cmdOpts()],
1275
+ ['roster', cmdOpts('hub', 'crew', 'candidate', 'display-name', 'model', 'as')],
1256
1276
  ['enrollments', cmdOpts('hub')],
1257
1277
  ['mcp', cmdOpts('hub')],
1258
1278
  ['work', cmdOpts()],
@@ -1274,10 +1294,10 @@ export const COMMAND_OPTIONS = new Map([
1274
1294
  ['green', cmdOpts('value', 'terminal')],
1275
1295
  ['emit', cmdOpts('items')],
1276
1296
  ['seal', cmdOpts('value')],
1277
- ['reject', cmdOpts('by', 'text')],
1297
+ ['reject', cmdOpts('by', 'text', 'requested')],
1278
1298
  ['retract', cmdOpts('by', 'text')],
1279
1299
  ['skip', cmdOpts('by', 'text')],
1280
- ['retry', cmdOpts('by', 'text')],
1300
+ ['retry', cmdOpts('by', 'text', 'hub')],
1281
1301
  ['ask', cmdOpts('by', 'question')],
1282
1302
  ['inbox', cmdOpts()],
1283
1303
  ['close', cmdOpts('outcome', 'summary')],
@@ -1356,20 +1376,259 @@ function preflight(command, args, io) {
1356
1376
  assertKnownOptions(command, args);
1357
1377
  return undefined;
1358
1378
  }
1359
- function dispatchRoster(io, args) {
1360
- if (args.positionals[1] !== 'show' || args.positionals.length > 3) {
1361
- throw new CliError('usage: owenloop roster show [crew]');
1379
+ function rosterAge(fetchedAt) {
1380
+ const seconds = Math.max(0, Math.floor((Date.now() - fetchedAt) / 1_000));
1381
+ if (seconds < 60)
1382
+ return `${seconds}s ago`;
1383
+ if (seconds < 3_600)
1384
+ return `${Math.floor(seconds / 60)}m ago`;
1385
+ if (seconds < 86_400)
1386
+ return `${Math.floor(seconds / 3_600)}h ago`;
1387
+ return `${Math.floor(seconds / 86_400)}d ago`;
1388
+ }
1389
+ // Keep these wire checks aligned with hub-core's roster and harness verbs.
1390
+ // This CLI is a separately deployable client, so it mirrors the public
1391
+ // contract rather than importing the service implementation.
1392
+ const MAX_ROSTER_IDENTIFIER_LENGTH = 200;
1393
+ const MAX_ROSTER_CAPABILITY_LENGTH = 64;
1394
+ const MAX_ROSTER_CANDIDATES = 32;
1395
+ const MAX_HARNESS_MODELS = 256;
1396
+ const ROSTER_EFFORTS = new Set(['low', 'medium', 'high', 'xhigh', 'max']);
1397
+ /**
1398
+ * The run's rate-limit priority band. Fixed by the routing plan's §4.8 wire
1399
+ * contract, not by hub discretion, so an out-of-set value is a local usage
1400
+ * error rather than a forwarded request the hub has to refuse.
1401
+ */
1402
+ const START_PRIORITIES = new Set(['low', 'normal', 'high']);
1403
+ function isRosterIdentifier(value) {
1404
+ return typeof value === 'string' && value.length > 0 && value.length <= MAX_ROSTER_IDENTIFIER_LENGTH && value.trim() === value;
1405
+ }
1406
+ function parseRosterIdentifier(value, label) {
1407
+ if (!isRosterIdentifier(value)) {
1408
+ throw new CliError(`${label} must be a trimmed, non-empty string of at most ${MAX_ROSTER_IDENTIFIER_LENGTH} characters`);
1362
1409
  }
1363
- const crew = args.positionals[2];
1364
- const layers = machineRosterLayers(io.env, crew);
1365
- const merged = mergeRosterLayers(layers);
1366
- const hasRoster = layers.some((layer) => layer.roster !== undefined);
1367
- if (!hasRoster) {
1368
- io.out(crew === undefined
1369
- ? 'no machine-global crew roster found'
1370
- : `no roster layers found for crew ${crew}`);
1410
+ return value;
1411
+ }
1412
+ function parseRosterCapability(value) {
1413
+ const capability = value.trim();
1414
+ if (capability === '')
1415
+ throw new CliError('capability must not be empty');
1416
+ if (capability.length > MAX_ROSTER_CAPABILITY_LENGTH) {
1417
+ throw new CliError(`capability must be at most ${MAX_ROSTER_CAPABILITY_LENGTH} characters`);
1371
1418
  }
1372
- else {
1419
+ if (capability.startsWith('personal:'))
1420
+ throw new CliError("capability must not start with the reserved prefix 'personal:'");
1421
+ return capability;
1422
+ }
1423
+ function isRosterCapability(value) {
1424
+ return typeof value === 'string' && value === value.trim() && value.length > 0 &&
1425
+ value.length <= MAX_ROSTER_CAPABILITY_LENGTH && !value.startsWith('personal:');
1426
+ }
1427
+ function isRosterCrewName(value) {
1428
+ // `personal:<id>`, slash, backslash, and `..` are all valid hub names. Only
1429
+ // the service's ordinary non-empty, trimmed, 64-character crew invariant is
1430
+ // relevant at this transport boundary.
1431
+ return typeof value === 'string' && value === value.trim() && value.length > 0 && value.length <= 64;
1432
+ }
1433
+ function isRosterEffort(value) {
1434
+ return typeof value === 'string' && ROSTER_EFFORTS.has(value);
1435
+ }
1436
+ function parseRosterDisplayName(value) {
1437
+ if (value.length > MAX_ROSTER_IDENTIFIER_LENGTH) {
1438
+ throw new CliError(`displayName must be a string of at most ${MAX_ROSTER_IDENTIFIER_LENGTH} characters`);
1439
+ }
1440
+ return value;
1441
+ }
1442
+ function parseRosterCandidate(value) {
1443
+ const first = value.indexOf(':');
1444
+ const lastColon = value.lastIndexOf(':');
1445
+ if (first <= 0 || lastColon <= first || lastColon === value.length - 1) {
1446
+ throw new CliError(`invalid --candidate '${value}' — expected <harness>:<model>:<effort>`);
1447
+ }
1448
+ const harness = parseRosterIdentifier(value.slice(0, first), 'candidate harness');
1449
+ const model = parseRosterIdentifier(value.slice(first + 1, lastColon), 'candidate model');
1450
+ const effort = value.slice(lastColon + 1);
1451
+ if (!isRosterEffort(effort)) {
1452
+ throw new CliError(`invalid --candidate '${value}' — effort must be one of low, medium, high, xhigh, max`);
1453
+ }
1454
+ return { harness, model, effort };
1455
+ }
1456
+ function parseRegistryModel(value) {
1457
+ const colon = value.lastIndexOf(':');
1458
+ if (colon <= 0) {
1459
+ throw new CliError(`invalid --model '${value}' — expected <model>:<effort,effort…>`);
1460
+ }
1461
+ const model = parseRosterIdentifier(value.slice(0, colon), 'model');
1462
+ const rawEfforts = value.slice(colon + 1);
1463
+ // The service permits an empty effort list. A malformed member (including
1464
+ // `high,`) still fails before hub/credential I/O, matching its `isEffort`.
1465
+ const efforts = rawEfforts === '' ? [] : rawEfforts.split(',');
1466
+ if (efforts.some((effort) => !isRosterEffort(effort))) {
1467
+ throw new CliError(`invalid --model '${value}' — efforts must be drawn from low, medium, high, xhigh, max`);
1468
+ }
1469
+ return { model, efforts };
1470
+ }
1471
+ function nullableId(value, prefix, field) {
1472
+ if (value === null)
1473
+ return null;
1474
+ if (typeof value !== 'string' || value === '')
1475
+ throw new CliError(`${prefix} — ${field} must be a non-empty string or null`);
1476
+ return value;
1477
+ }
1478
+ /** Narrow each mutation response before stdout claims the write succeeded. */
1479
+ function validateRosterMutationSuccess(endpoint, body) {
1480
+ const prefix = `${endpoint}: malformed success response`;
1481
+ const row = recordOf(body);
1482
+ if (row === null)
1483
+ throw new CliError(`${prefix} — not an object`);
1484
+ if (endpoint === 'put_roster') {
1485
+ const crewId = nullableId(row.crewId, prefix, 'crewId');
1486
+ const crewName = nullableId(row.crewName, prefix, 'crewName');
1487
+ if (!isRosterCapability(row.capability))
1488
+ throw new CliError(`${prefix} — missing valid capability`);
1489
+ if (!Array.isArray(row.candidates))
1490
+ throw new CliError(`${prefix} — missing array candidates`);
1491
+ const candidates = row.candidates.map((candidate, index) => {
1492
+ const value = recordOf(candidate);
1493
+ if (value === null)
1494
+ throw new CliError(`${prefix} — candidates[${index}] is not an object`);
1495
+ if (!isRosterIdentifier(value.harness) || !isRosterIdentifier(value.model) || !isRosterEffort(value.effort)) {
1496
+ throw new CliError(`${prefix} — candidates[${index}] has an invalid harness, model, or effort`);
1497
+ }
1498
+ return { harness: value.harness, model: value.model, effort: value.effort };
1499
+ });
1500
+ if (!Array.isArray(row.warnings) || row.warnings.some((warning) => typeof warning !== 'string')) {
1501
+ throw new CliError(`${prefix} — missing array warnings`);
1502
+ }
1503
+ return { crewId, crewName, capability: row.capability, candidates, warnings: row.warnings };
1504
+ }
1505
+ if (endpoint === 'delete_roster_row') {
1506
+ const crewId = nullableId(row.crewId, prefix, 'crewId');
1507
+ if (!isRosterCapability(row.capability))
1508
+ throw new CliError(`${prefix} — missing valid capability`);
1509
+ if (typeof row.removed !== 'boolean')
1510
+ throw new CliError(`${prefix} — missing boolean removed`);
1511
+ return { crewId, capability: row.capability, removed: row.removed };
1512
+ }
1513
+ if (!isRosterIdentifier(row.harness))
1514
+ throw new CliError(`${prefix} — missing valid harness`);
1515
+ if (typeof row.displayName !== 'string' || row.displayName.length > MAX_ROSTER_IDENTIFIER_LENGTH) {
1516
+ throw new CliError(`${prefix} — displayName must be a string of at most ${MAX_ROSTER_IDENTIFIER_LENGTH} characters`);
1517
+ }
1518
+ if (!Array.isArray(row.models))
1519
+ throw new CliError(`${prefix} — missing array models`);
1520
+ const models = row.models.map((model, index) => {
1521
+ const value = recordOf(model);
1522
+ if (value === null)
1523
+ throw new CliError(`${prefix} — models[${index}] is not an object`);
1524
+ if (!isRosterIdentifier(value.model))
1525
+ throw new CliError(`${prefix} — models[${index}] missing valid model`);
1526
+ if (!Array.isArray(value.efforts) || value.efforts.some((effort) => !isRosterEffort(effort))) {
1527
+ throw new CliError(`${prefix} — models[${index}] missing array efforts`);
1528
+ }
1529
+ if (typeof value.updatedAt !== 'number' || !Number.isFinite(value.updatedAt))
1530
+ throw new CliError(`${prefix} — models[${index}] missing finite number updatedAt`);
1531
+ if (typeof value.updatedBy !== 'string' || value.updatedBy === '')
1532
+ throw new CliError(`${prefix} — models[${index}] missing non-empty string updatedBy`);
1533
+ return { model: value.model, efforts: value.efforts, updatedAt: value.updatedAt, updatedBy: value.updatedBy };
1534
+ });
1535
+ return { harness: row.harness, displayName: row.displayName, models };
1536
+ }
1537
+ function validateRosterRows(value, prefix) {
1538
+ const row = recordOf(value);
1539
+ if (row === null)
1540
+ throw new CliError(`${prefix} — roster must be an object`);
1541
+ // Hub capability names may legally collide with Object.prototype (notably
1542
+ // `__proto__`). A normal object assignment would mutate/drop that row.
1543
+ const result = Object.create(null);
1544
+ for (const [capability, candidates] of Object.entries(row)) {
1545
+ if (!isRosterCapability(capability))
1546
+ throw new CliError(`${prefix} — invalid capability ${JSON.stringify(capability)}`);
1547
+ if (!Array.isArray(candidates))
1548
+ throw new CliError(`${prefix} — ${capability} must be an array`);
1549
+ result[capability] = candidates.map((candidate, index) => {
1550
+ const item = recordOf(candidate);
1551
+ if (item === null || !isRosterIdentifier(item.harness) || !isRosterIdentifier(item.model) || !isRosterEffort(item.effort)) {
1552
+ throw new CliError(`${prefix} — ${capability}[${index}] must contain valid harness, model, and effort`);
1553
+ }
1554
+ return { harness: item.harness, model: item.model, effort: item.effort };
1555
+ });
1556
+ }
1557
+ return result;
1558
+ }
1559
+ function validateGetRostersSuccess(body) {
1560
+ const prefix = 'rosters: malformed success response';
1561
+ const row = recordOf(body);
1562
+ if (row === null || !Array.isArray(row.crews))
1563
+ throw new CliError(`${prefix} — expected global object and crews array`);
1564
+ return {
1565
+ global: validateRosterRows(row.global, prefix),
1566
+ crews: row.crews.map((crew, index) => {
1567
+ const item = recordOf(crew);
1568
+ if (item === null || typeof item.crewId !== 'string' || item.crewId === '' || !(isRosterCrewName(item.crewName) || item.crewName === null)) {
1569
+ throw new CliError(`${prefix} — crews[${index}] has an invalid identity`);
1570
+ }
1571
+ return { crewId: item.crewId, crewName: item.crewName, roster: validateRosterRows(item.roster, `${prefix} — crews[${index}].roster`) };
1572
+ }),
1573
+ };
1574
+ }
1575
+ function validateHarnessModelsSuccess(body) {
1576
+ const prefix = 'harness_models: malformed success response';
1577
+ const row = recordOf(body);
1578
+ if (row === null || !Array.isArray(row.harnesses) || !Array.isArray(row.models))
1579
+ throw new CliError(`${prefix} — expected harnesses and models arrays`);
1580
+ return {
1581
+ harnesses: row.harnesses.map((harness, index) => {
1582
+ const item = recordOf(harness);
1583
+ if (item === null || !isRosterIdentifier(item.harness) || typeof item.displayName !== 'string' || item.displayName.length > MAX_ROSTER_IDENTIFIER_LENGTH)
1584
+ throw new CliError(`${prefix} — harnesses[${index}] is invalid`);
1585
+ return { harness: item.harness, displayName: item.displayName };
1586
+ }),
1587
+ models: row.models.map((model, index) => {
1588
+ const item = recordOf(model);
1589
+ if (item === null || !isRosterIdentifier(item.harness) || !isRosterIdentifier(item.model) || !Array.isArray(item.efforts) || item.efforts.some((effort) => !isRosterEffort(effort)) || typeof item.updatedAt !== 'number' || !Number.isFinite(item.updatedAt) || typeof item.updatedBy !== 'string' || item.updatedBy === '')
1590
+ throw new CliError(`${prefix} — models[${index}] is invalid`);
1591
+ return { harness: item.harness, model: item.model, efforts: item.efforts, updatedAt: item.updatedAt, updatedBy: item.updatedBy };
1592
+ }),
1593
+ };
1594
+ }
1595
+ /** `roster` uses the same authenticated REST ladders as `routing`; show stays
1596
+ * fully offline so it reports exactly what an agent-run child would route. */
1597
+ async function dispatchRoster(io, args) {
1598
+ const USAGE_FORMS = 'usage: owenloop roster show [crew] | owenloop roster org [--hub <url>] | ' +
1599
+ 'owenloop roster org put <capability> [--crew <name>] --candidate <harness>:<model>:<effort>… [--hub <url>] | ' +
1600
+ 'owenloop roster org rm <capability> [--crew <name>] [--hub <url>] | ' +
1601
+ 'owenloop roster registry [--hub <url>] | owenloop roster registry put <harness> [--display-name <text>] [--model <model>:<effort,effort…>]… [--hub <url>] | ' +
1602
+ 'owenloop roster sync [--hub <url>] [--as agent|agent:<account>]';
1603
+ const sub = args.positionals[1];
1604
+ if (sub !== 'show' && sub !== 'org' && sub !== 'registry' && sub !== 'sync') {
1605
+ throw new CliError(`unknown roster subcommand '${sub ?? ''}' — ${USAGE_FORMS}`);
1606
+ }
1607
+ // `COMMAND_OPTIONS` admits the union of every roster flag. Narrow it again
1608
+ // by command form before even an offline read or credential lookup, so a
1609
+ // typo never looks like a successful command that silently ignored intent.
1610
+ const assertFormOptions = (allowed) => {
1611
+ // `--db` and `--defs` are global CLI options. They are admitted before
1612
+ // dispatch for every command and must remain accepted here too; this
1613
+ // narrower check is only for roster-form-specific flags.
1614
+ const allowedSet = new Set([...GLOBAL_OPTIONS, ...allowed]);
1615
+ const disallowed = [...args.options.keys()].filter((option) => !allowedSet.has(option));
1616
+ if (disallowed.length > 0) {
1617
+ throw new CliError(`${disallowed.map((option) => `--${option}`).join(', ')} ${disallowed.length === 1 ? 'is' : 'are'} not valid for this roster command (${USAGE_FORMS})`);
1618
+ }
1619
+ };
1620
+ if (sub === 'show') {
1621
+ assertFormOptions([]);
1622
+ if (args.positionals.length > 3)
1623
+ throw new CliError(USAGE_FORMS);
1624
+ const crew = args.positionals[2];
1625
+ const settings = loadSettings(io.env);
1626
+ const account = io.env.OWENLOOP_ACCOUNT ?? 'default';
1627
+ const layers = effectiveRosterLayers(io.env, crew, { origin: settings.hubOrigin, account });
1628
+ const merged = mergeRosterLayers(layers);
1629
+ const cache = settings.hubOrigin === undefined ? undefined : readHubRosterCache(io.env, settings.hubOrigin, account);
1630
+ if (Object.keys(merged).length === 0)
1631
+ io.out(crew === undefined ? 'no roster layers found' : `no roster rows found for crew ${crew}`);
1373
1632
  for (const capability of Object.keys(merged).sort()) {
1374
1633
  const entry = merged[capability];
1375
1634
  io.out(`${capability}:`);
@@ -1377,11 +1636,198 @@ function dispatchRoster(io, args) {
1377
1636
  io.out(` [${index}] harness=${candidate.harness} model=${candidate.model} effort=${candidate.effort} from ${entry.source}`);
1378
1637
  }
1379
1638
  }
1639
+ io.out('layers inspected:');
1640
+ for (const layer of layers) {
1641
+ const age = layer.source.startsWith('hub ') && cache?.kind === 'hit' ? `; ${rosterAge(cache.data.fetchedAt)}` : '';
1642
+ io.out(` ${layer.source}: ${layer.roster === undefined ? 'absent' : 'found'}${layer.path === undefined ? '' : ` (${layer.path})`}${age}`);
1643
+ }
1644
+ const shadows = explainRosterShadows(layers);
1645
+ const shadowed = Object.entries(shadows).filter(([, detail]) => detail.shadowed.length > 0).sort(([a], [b]) => a.localeCompare(b));
1646
+ if (shadowed.length > 0) {
1647
+ io.out('shadowed:');
1648
+ for (const [capability, detail] of shadowed) {
1649
+ io.out(` ${capability}: ${detail.winner} wins; ${detail.shadowed.map((row) => `${row.source} (${row.candidateCount} candidate${row.candidateCount === 1 ? '' : 's'})`).join(', ')} shadowed`);
1650
+ }
1651
+ }
1652
+ return 0;
1380
1653
  }
1381
- io.out('layers inspected:');
1382
- for (const layer of layers) {
1383
- io.out(` ${layer.source}: ${layer.roster === undefined ? 'absent' : 'found'}${layer.path === undefined ? '' : ` (${layer.path})`}`);
1654
+ let orgSub;
1655
+ let registrySub;
1656
+ let capability = '';
1657
+ let harness = '';
1658
+ if (sub === 'org') {
1659
+ const nested = args.positionals[2];
1660
+ if (nested === undefined)
1661
+ orgSub = 'get';
1662
+ else if (nested === 'put' || nested === 'rm')
1663
+ orgSub = nested;
1664
+ else
1665
+ throw new CliError(`unknown roster org subcommand '${nested}' — ${USAGE_FORMS}`);
1666
+ if (orgSub === 'put' || orgSub === 'rm') {
1667
+ capability = parseRosterCapability(args.positionals[3] ?? '');
1668
+ }
1669
+ const maxPositionals = orgSub === 'get' ? 2 : 4;
1670
+ if (args.positionals.length > maxPositionals)
1671
+ throw new CliError(USAGE_FORMS);
1672
+ assertFormOptions(orgSub === 'get' ? ['hub'] : orgSub === 'put' ? ['hub', 'crew', 'candidate'] : ['hub', 'crew']);
1673
+ if (orgSub === 'put' && all(args, 'candidate').length === 0)
1674
+ throw new CliError(`missing required --candidate (${USAGE_FORMS})`);
1675
+ }
1676
+ else if (sub === 'registry') {
1677
+ const nested = args.positionals[2];
1678
+ if (nested === undefined)
1679
+ registrySub = 'get';
1680
+ else if (nested === 'put')
1681
+ registrySub = 'put';
1682
+ else
1683
+ throw new CliError(`unknown roster registry subcommand '${nested}' — ${USAGE_FORMS}`);
1684
+ if (registrySub === 'put')
1685
+ harness = parseRosterIdentifier(args.positionals[3] ?? '', 'harness');
1686
+ const maxPositionals = registrySub === 'get' ? 2 : 4;
1687
+ if (args.positionals.length > maxPositionals)
1688
+ throw new CliError(USAGE_FORMS);
1689
+ assertFormOptions(registrySub === 'get' ? ['hub'] : ['hub', 'display-name', 'model']);
1384
1690
  }
1691
+ else if (args.positionals.length > 2) {
1692
+ throw new CliError(USAGE_FORMS);
1693
+ }
1694
+ else {
1695
+ assertFormOptions(['hub', 'as']);
1696
+ }
1697
+ const crewOption = last(args, 'crew');
1698
+ if (crewOption !== undefined && (args.missingOptionValues.has('crew') || crewOption.trim() === '')) {
1699
+ throw new CliError(`--crew requires a non-empty crew name (${USAGE_FORMS})`);
1700
+ }
1701
+ if (crewOption !== undefined && !isRosterCrewName(crewOption)) {
1702
+ throw new CliError('--crew must be a trimmed, non-empty crew name of at most 64 characters');
1703
+ }
1704
+ // Finish every command-local parse before resolving a hub or consulting the
1705
+ // credential backend. An invalid payload is a usage error, not a reason to
1706
+ // run an external credential helper or mask it as a missing credential.
1707
+ let parsedCandidates;
1708
+ let parsedModels;
1709
+ let parsedDisplayName;
1710
+ if (sub === 'org' && orgSub === 'put') {
1711
+ const rawCandidates = all(args, 'candidate');
1712
+ if (rawCandidates.length > MAX_ROSTER_CANDIDATES) {
1713
+ throw new CliError(`--candidate may be supplied at most ${MAX_ROSTER_CANDIDATES} times`);
1714
+ }
1715
+ parsedCandidates = rawCandidates.map(parseRosterCandidate);
1716
+ const candidateKeys = new Set();
1717
+ for (const candidate of parsedCandidates) {
1718
+ const key = JSON.stringify([candidate.harness, candidate.model, candidate.effort]);
1719
+ if (candidateKeys.has(key))
1720
+ throw new CliError('duplicate --candidate harness, model, and effort triple');
1721
+ candidateKeys.add(key);
1722
+ }
1723
+ }
1724
+ if (sub === 'registry' && registrySub === 'put') {
1725
+ const displayNames = all(args, 'display-name');
1726
+ if (displayNames.length > 1)
1727
+ throw new CliError('--display-name may be supplied at most once');
1728
+ if (displayNames.length > 0 && args.missingOptionValues.has('display-name')) {
1729
+ throw new CliError('--display-name requires a value');
1730
+ }
1731
+ if (displayNames.length === 1)
1732
+ parsedDisplayName = parseRosterDisplayName(displayNames[0]);
1733
+ const rawModels = all(args, 'model');
1734
+ if (rawModels.length > MAX_HARNESS_MODELS)
1735
+ throw new CliError(`--model may be supplied at most ${MAX_HARNESS_MODELS} times`);
1736
+ // A zero-model full snapshot is a supported way to clear the advisory
1737
+ // registry. An empty display label is likewise a deliberate service value.
1738
+ parsedModels = rawModels.map(parseRegistryModel);
1739
+ const modelNames = new Set();
1740
+ for (const model of parsedModels) {
1741
+ if (modelNames.has(model.model))
1742
+ throw new CliError(`duplicate --model '${model.model}'`);
1743
+ modelNames.add(model.model);
1744
+ }
1745
+ }
1746
+ // `roster sync` is an agent-owned cache refresh. Unlike the other roster
1747
+ // verbs, its omitted `--as` deliberately means the default agent slot.
1748
+ const slot = sub === 'sync'
1749
+ ? (!args.options.has('as') ? { principal: 'agent' } : resolveSlot(args))
1750
+ : { principal: 'human' };
1751
+ if (sub === 'sync' && slot.principal !== 'agent') {
1752
+ throw new CliError(`roster sync requires an agent credential — pass --as agent or --as agent:<account> (${USAGE_FORMS})`);
1753
+ }
1754
+ const origin = resolveAgentHub(io, args, sub === 'sync' ? 'sync rosters from' : 'manage rosters on');
1755
+ const cred = readCredential(io, origin, slot);
1756
+ if (cred === null)
1757
+ throw new CliError(emptySlotMessage(origin, slot), { exitCode: 3 });
1758
+ const getJson = async (path, prefix) => {
1759
+ const { res, cred: used } = await authedGet(io, origin, slot, cred, path);
1760
+ if (res.status === 401) {
1761
+ throw new CliError(used.kind === 'agent'
1762
+ ? 'token revoked or invalid — re-mint it in the console or run `owenloop login`'
1763
+ : 'credential rejected by the hub — run `owenloop login`', { exitCode: 3 });
1764
+ }
1765
+ if (!res.ok)
1766
+ throw new CliError((await hubRequestMessage(res)) ?? `hub ${origin} rejected the request (HTTP ${res.status})`);
1767
+ try {
1768
+ return await res.json();
1769
+ }
1770
+ catch {
1771
+ throw new CliError(`${prefix}: malformed response — body is not valid JSON`);
1772
+ }
1773
+ };
1774
+ if (sub === 'sync') {
1775
+ const account = slot.principal === 'agent' ? slot.account ?? 'default' : 'default';
1776
+ // Use the same sync helper as shift start and periodic refresh. The local
1777
+ // adapter preserves the CLI's credential-refresh/error ladder rather than
1778
+ // bypassing it with a second raw-fetch implementation.
1779
+ const cacheClient = {
1780
+ whoami: async () => getJson('/api/whoami', 'whoami'),
1781
+ getRosters: async () => getJson('/api/rosters', 'rosters'),
1782
+ };
1783
+ await syncHubRosterCache({
1784
+ client: cacheClient,
1785
+ env: io.env,
1786
+ origin,
1787
+ account,
1788
+ });
1789
+ const cache = readHubRosterCache(io.env, origin, account);
1790
+ if (cache.kind !== 'hit')
1791
+ throw new CliError(`roster sync wrote no readable cache: ${cache.reason}`);
1792
+ print(io, { ok: true, hub: origin, cachePath: cache.path, fetchedAt: cache.data.fetchedAt });
1793
+ return 0;
1794
+ }
1795
+ if (sub === 'org' && orgSub === 'get') {
1796
+ print(io, { ok: true, hub: origin, rosters: validateGetRostersSuccess(await getJson('/api/rosters', 'rosters')) });
1797
+ return 0;
1798
+ }
1799
+ if (sub === 'registry' && registrySub === 'get') {
1800
+ print(io, { ok: true, hub: origin, registry: validateHarnessModelsSuccess(await getJson('/api/harness_models', 'harness_models')) });
1801
+ return 0;
1802
+ }
1803
+ let endpoint;
1804
+ let payload;
1805
+ if (sub === 'org' && orgSub === 'put') {
1806
+ endpoint = 'put_roster';
1807
+ payload = { capability, candidates: parsedCandidates, ...(crewOption === undefined ? {} : { crew: crewOption }) };
1808
+ }
1809
+ else if (sub === 'org') {
1810
+ endpoint = 'delete_roster_row';
1811
+ payload = { capability, ...(crewOption === undefined ? {} : { crew: crewOption }) };
1812
+ }
1813
+ else {
1814
+ endpoint = 'put_harness_models';
1815
+ payload = { harness, models: parsedModels, ...(parsedDisplayName === undefined ? {} : { displayName: parsedDisplayName }) };
1816
+ }
1817
+ const { res } = await authedPost(io, origin, slot, cred, `/api/${endpoint}`, payload);
1818
+ if (res.status === 401)
1819
+ throw new CliError('credential rejected by the hub — run `owenloop login`', { exitCode: 3 });
1820
+ if (!res.ok)
1821
+ throw new CliError((await hubRequestMessage(res)) ?? `hub ${origin} rejected the request (HTTP ${res.status})`);
1822
+ let body;
1823
+ try {
1824
+ body = await res.json();
1825
+ }
1826
+ catch {
1827
+ throw new CliError(`${endpoint}: malformed success response — body is not valid JSON`);
1828
+ }
1829
+ const result = validateRosterMutationSuccess(endpoint, body);
1830
+ print(io, { ok: true, hub: origin, result });
1385
1831
  return 0;
1386
1832
  }
1387
1833
  function dispatch(command, io, args) {
@@ -1390,8 +1836,6 @@ function dispatch(command, io, args) {
1390
1836
  io.out(USAGE);
1391
1837
  return 0;
1392
1838
  }
1393
- if (command === 'roster')
1394
- return dispatchRoster(io, args);
1395
1839
  if (command === 'lint') {
1396
1840
  const defsDir = last(args, 'defs') ?? io.env.OWENLOOP_DEFS ?? join(io.cwd, 'workflows');
1397
1841
  const failures = [];
@@ -1899,8 +2343,9 @@ function dispatch(command, io, args) {
1899
2343
  const path = need(args, 2, 'path');
1900
2344
  const by = needOpt(args, 'by');
1901
2345
  const text = needOpt(args, 'text');
1902
- const rejectRes = engine.reject(wf, path, by, text);
1903
- print(io, { ok: true, action: 'reject', path, outcome: rejectRes.outcome });
2346
+ const requested = last(args, 'requested');
2347
+ const rejectRes = engine.reject(wf, path, by, text, requested);
2348
+ print(io, { ok: true, action: 'reject', path, outcome: rejectRes.outcome, ...(requested !== undefined ? { requested } : {}) });
1904
2349
  // §24.4/§4.6: a judge's reject can itself be born-rejected by the CAS
1905
2350
  // guard (stale verdict against a submission that already moved on) —
1906
2351
  // mirror the 'green' handler above: that is a failure, not a success,
@@ -4076,6 +4521,14 @@ async function dispatchStart(io, args) {
4076
4521
  // than a silent unmodified run. Omitting the flag entirely IS the unmodified
4077
4522
  // run — that is the difference `requiredTextOption` preserves.
4078
4523
  const modifier = requiredTextOption('modifier', 'name');
4524
+ // Free routing label. No registry and no enumeration by design (§4.8), so the
4525
+ // only shape check is the one every text option gets: present-but-valueless and
4526
+ // explicitly-empty are usage errors; omitted is omitted.
4527
+ const scope = requiredTextOption('scope', 'label');
4528
+ const priority = requiredTextOption('priority', 'low|normal|high');
4529
+ if (priority !== undefined && !START_PRIORITIES.has(priority)) {
4530
+ throw new CliError(`invalid --priority '${priority}' — must be one of low, normal, high`);
4531
+ }
4079
4532
  const origin = resolveStartHub(io, args);
4080
4533
  const slot = { principal: 'human' };
4081
4534
  const cred = readCredential(io, origin, slot);
@@ -4092,6 +4545,8 @@ async function dispatchStart(io, args) {
4092
4545
  // absent as the same thing, but sending an explicit `undefined` would put a
4093
4546
  // `modifier` key in the JSON body with a null value. Omitted means omitted.
4094
4547
  ...(modifier !== undefined ? { modifier } : {}),
4548
+ ...(scope !== undefined ? { scope } : {}),
4549
+ ...(priority !== undefined ? { priority } : {}),
4095
4550
  };
4096
4551
  const { res, cred: used } = await authedPost(io, origin, slot, cred, '/api/start_run', request);
4097
4552
  if (res.status === 401)
@@ -4133,6 +4588,11 @@ async function dispatchStart(io, args) {
4133
4588
  // accepted exactly this value. Printed only when the flag was passed, so an
4134
4589
  // unmodified run's output is byte-identical to what it was before.
4135
4590
  ...(modifier !== undefined ? { modifier } : {}),
4591
+ // Echoed from the request, like `modifier` above, and only when the flag
4592
+ // was passed. A run started without these flags prints exactly what it did
4593
+ // before, while a hub refusal prevents this success output entirely.
4594
+ ...(scope !== undefined ? { scope } : {}),
4595
+ ...(priority !== undefined ? { priority } : {}),
4136
4596
  ...(Array.isArray(wire.stampedCrews) ? { stampedCrews: wire.stampedCrews } : {}),
4137
4597
  ...(Array.isArray(wire.validatedCrews) ? { validatedCrews: wire.validatedCrews } : {}),
4138
4598
  });
@@ -4220,6 +4680,44 @@ async function dispatchCancel(io, args) {
4220
4680
  });
4221
4681
  return 0;
4222
4682
  }
4683
+ /**
4684
+ * `owenloop retry --hub` — the human stall-clear / answer path for a hub-hosted
4685
+ * run. Local retry remains synchronous in `main()`; this dispatch owns only
4686
+ * the network half so direct synchronous callers keep their existing contract.
4687
+ */
4688
+ async function dispatchRetry(io, args) {
4689
+ const workflow = need(args, 1, 'workflow');
4690
+ const path = need(args, 2, 'path');
4691
+ if (args.options.has('by')) {
4692
+ throw new CliError('owenloop retry: --by cannot be combined with --hub — the hub attributes the retry to the authenticated human principal');
4693
+ }
4694
+ if (args.missingOptionValues.has('text')) {
4695
+ throw new CliError('missing value for --text: expected --text <guidance>');
4696
+ }
4697
+ const text = last(args, 'text');
4698
+ if (text !== undefined && text.trim() === '') {
4699
+ throw new CliError('invalid empty value for --text: expected --text <guidance>');
4700
+ }
4701
+ const origin = resolveStartHub(io, args);
4702
+ const slot = { principal: 'human' };
4703
+ const cred = readCredential(io, origin, slot);
4704
+ if (cred === null) {
4705
+ throw new CliError(`no human credential for ${origin} — run: owenloop login --hub ${origin}`, { exitCode: 3 });
4706
+ }
4707
+ const request = { workflow, path, ...(text !== undefined ? { text } : {}) };
4708
+ const { res, cred: used } = await authedPost(io, origin, slot, cred, '/api/retry_artifact', request);
4709
+ if (res.status === 401)
4710
+ assertAuthOk(res, used, origin);
4711
+ if (!res.ok) {
4712
+ const message = await hubRequestMessage(res);
4713
+ throw new CliError(message ?? `hub ${origin} rejected the request (HTTP ${res.status})`);
4714
+ }
4715
+ // The hub owns the response body contract. Any successful response has
4716
+ // completed the state transition, so expose a stable CLI receipt instead of
4717
+ // assuming fields the server has not promised this client.
4718
+ print(io, { ok: true, action: 'retry', path, workflow, hub: origin });
4719
+ return 0;
4720
+ }
4223
4721
  /**
4224
4722
  * `owenloop instance` — read a HUB instance's live state from the terminal.
4225
4723
  *
@@ -5452,6 +5950,79 @@ async function dispatchCrew(io, args) {
5452
5950
  throw e;
5453
5951
  }
5454
5952
  }
5953
+ /** Probe before any mkdir or temporary write. An existing operator file is a
5954
+ * successful no-op; every other existing filesystem object remains an error. */
5955
+ function hasExistingCrewRosterTarget(path) {
5956
+ try {
5957
+ const target = lstatSync(path);
5958
+ if (!target.isFile())
5959
+ throw new Error(`crew roster target exists but is not a regular file: ${path}`);
5960
+ return true;
5961
+ }
5962
+ catch (error) {
5963
+ if (error.code === 'ENOENT')
5964
+ return false;
5965
+ throw error;
5966
+ }
5967
+ }
5968
+ /**
5969
+ * Install a fully-written strongest-layer roster without replacing an
5970
+ * operator's file. Only EEXIST from the final exclusive link is interpreted
5971
+ * as an existing target; failures creating its parent or temporary file stay
5972
+ * failures instead of being misreported as a harmless skip.
5973
+ */
5974
+ export function installCrewRosterIfAbsent(path, contents, options = {}) {
5975
+ // This is deliberately before mkdir/temp creation: a setup rerun must be a
5976
+ // zero-write no-op even in a read-only or full directory.
5977
+ if (hasExistingCrewRosterTarget(path))
5978
+ return 'existing';
5979
+ const dir = dirname(path);
5980
+ mkdirSync(dir, { recursive: true });
5981
+ const temp = join(dir, options.tempName?.() ?? `.${randomUUID()}.roster.tmp`);
5982
+ let tempWritten = false;
5983
+ try {
5984
+ try {
5985
+ (options.writeTemp ?? ((candidate, body) => writeFileSync(candidate, body, { encoding: 'utf8', flag: 'wx' })))(temp, contents);
5986
+ tempWritten = true;
5987
+ }
5988
+ catch (error) {
5989
+ // `writeFileSync` can throw after creating a partial file (ENOSPC,
5990
+ // interruption). EEXIST is the one exception: that temp was never ours
5991
+ // and must not be removed. Every other failed write gets its partial
5992
+ // cleanup before the error reaches setup.
5993
+ if (error.code !== 'EEXIST') {
5994
+ try {
5995
+ unlinkSync(temp);
5996
+ }
5997
+ catch {
5998
+ // Nothing was created, or cleanup has no recovery path.
5999
+ }
6000
+ }
6001
+ throw error;
6002
+ }
6003
+ try {
6004
+ linkSync(temp, path);
6005
+ return 'created';
6006
+ }
6007
+ catch (error) {
6008
+ if (error.code !== 'EEXIST')
6009
+ throw error;
6010
+ // EEXIST is meaningful only for the target installation. Verify that it
6011
+ // is a real roster file before calling it an intentional operator file.
6012
+ if (!hasExistingCrewRosterTarget(path))
6013
+ throw error;
6014
+ return 'existing';
6015
+ }
6016
+ }
6017
+ finally {
6018
+ if (tempWritten) {
6019
+ try {
6020
+ unlinkSync(temp);
6021
+ }
6022
+ catch { /* target installation already decided; cleanup is best-effort */ }
6023
+ }
6024
+ }
6025
+ }
5455
6026
  /**
5456
6027
  * The plugin checks are rendered but NON-FATAL: a developer may use either
5457
6028
  * Claude Code or Codex, and a missing harness or failed plugin convergence must
@@ -5752,7 +6323,7 @@ export function resolveBundledMarketplaceRoot(harness) {
5752
6323
  return null;
5753
6324
  }
5754
6325
  function recordOf(value) {
5755
- return value !== null && typeof value === 'object' ? value : null;
6326
+ return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null;
5756
6327
  }
5757
6328
  function normalizedPluginVersion(value) {
5758
6329
  if (typeof value !== 'string')
@@ -6076,7 +6647,7 @@ async function registerMachineEnrollment(io, origin, humanCred, keys, humanRef,
6076
6647
  return done('machine key registered');
6077
6648
  }
6078
6649
  /**
6079
- * `owenloop setup` — converge this machine's install in seven probe→(skip|act)
6650
+ * `owenloop setup` — converge this machine's install in eight probe→(skip|act)
6080
6651
  * steps, idempotently: a second run performs ZERO writes (no store mutation, no
6081
6652
  * key generation, no settings write, no browser, no mint/rekey/register POST).
6082
6653
  * Each ACT is reached only through its probe failing.
@@ -6163,8 +6734,8 @@ async function dispatchSetup(io, args) {
6163
6734
  }
6164
6735
  const origin = resolveSetupHub(io, args);
6165
6736
  const steps = [];
6166
- // --- [1/7] inspect: zero writes, best-effort probes ---
6167
- io.err('[1/7] inspect');
6737
+ // --- [1/8] inspect: zero writes, best-effort probes ---
6738
+ io.err('[1/8] inspect');
6168
6739
  io.err(` human credential: ${readCredential(io, origin, { principal: 'human' }) !== null ? 'present' : 'none — will log in'}`);
6169
6740
  const inspectSettingsPath = owenloopSettingsPath(io.env);
6170
6741
  let settingsNote;
@@ -6189,8 +6760,8 @@ async function dispatchSetup(io, args) {
6189
6760
  ? ' agent slots: checked in step 3'
6190
6761
  : ` agent slots: ${inspectAccts.length ? inspectAccts.map((a) => `agent:${a}`).join(', ') : 'none'}`);
6191
6762
  steps.push({ step: 'inspect', action: 'done', detail: 'probed local state' });
6192
- // --- [2/7] human login: the hard gate that makes step 3's rekey legal ---
6193
- io.err('[2/7] human login');
6763
+ // --- [2/8] human login: the hard gate that makes step 3's rekey legal ---
6764
+ io.err('[2/8] human login');
6194
6765
  let humanCred = readCredential(io, origin, { principal: 'human' });
6195
6766
  let humanIdentity;
6196
6767
  if (humanCred !== null) {
@@ -6218,8 +6789,8 @@ async function dispatchSetup(io, args) {
6218
6789
  io.err(`✓ human: signed in as ${humanIdentity.email ?? humanIdentity.actor.id} @ ${humanIdentity.orgName}`);
6219
6790
  steps.push({ step: 'human login', action: 'done', detail: `signed in as ${humanIdentity.email ?? humanIdentity.actor.id}` });
6220
6791
  }
6221
- // --- [3/7] agent ---
6222
- io.err('[3/7] agent');
6792
+ // --- [3/8] agent ---
6793
+ io.err('[3/8] agent');
6223
6794
  const { res: idRes } = await authedGet(io, origin, { principal: 'human' }, humanCred, '/api/agent_identities');
6224
6795
  if (idRes.status === 403) {
6225
6796
  throw new CliError('setup needs an admin credential to manage Scoped Identities (hub returned 403)');
@@ -6230,12 +6801,14 @@ async function dispatchSetup(io, args) {
6230
6801
  candidateNames.add('default');
6231
6802
  const probe = await probeAgentSlots(io, origin, [...candidateNames], identities);
6232
6803
  let agentAccount;
6804
+ let agentCrews;
6233
6805
  // The stable principal id for the agent signing key: the hub's agent actor
6234
6806
  // id (`agentId`), which rekey preserves and mint mints fresh.
6235
6807
  let agentPrincipalId;
6236
6808
  if (probe.verified !== null) {
6237
6809
  agentAccount = probe.verified.name;
6238
6810
  agentPrincipalId = probe.verified.actorId;
6811
+ agentCrews = probe.verified.identity?.crews;
6239
6812
  const crewsStr = probe.verified.identity ? ` (crews: ${probe.verified.identity.crews.join(', ') || 'none'})` : '';
6240
6813
  io.err(`✓ agent: ${agentAccount}${crewsStr}`);
6241
6814
  steps.push({ step: 'agent', action: 'skipped', detail: `agent:${agentAccount} verified` });
@@ -6269,6 +6842,7 @@ async function dispatchSetup(io, args) {
6269
6842
  const result = await mintAgentCredential(io, origin, { principal: 'human' }, humanCred, { name: action.name, crews, scopes });
6270
6843
  agentAccount = action.name;
6271
6844
  agentPrincipalId = result.agentId;
6845
+ agentCrews = result.crews;
6272
6846
  io.err(`✓ agent: minted agent:${agentAccount} (crews: ${result.crews.join(', ') || 'none'}; scopes: ${result.scopes.join(', ')})`);
6273
6847
  steps.push({ step: 'agent', action: 'done', detail: `minted agent:${agentAccount}` });
6274
6848
  }
@@ -6280,10 +6854,10 @@ async function dispatchSetup(io, args) {
6280
6854
  steps.push({ step: 'agent', action: 'done', detail: `re-keyed agent:${agentAccount}` });
6281
6855
  }
6282
6856
  }
6283
- // --- [4/7] signing keys: human → machine → agent, idempotently ---
6857
+ // --- [4/8] signing keys: human → machine → agent, idempotently ---
6284
6858
  // Prints kind + state + backend ONLY. Never key bytes, fingerprints,
6285
6859
  // secret-store values, or reused private-key paths.
6286
- io.err('[4/7] signing keys');
6860
+ io.err('[4/8] signing keys');
6287
6861
  const keys = io.principalKeys ?? new PrincipalKeyManager({ env: io.env });
6288
6862
  const humanRef = { origin, kind: 'human', id: humanIdentity.actor.id };
6289
6863
  const machineRef = { origin, kind: 'machine', id: 'local' };
@@ -6306,8 +6880,8 @@ async function dispatchSetup(io, args) {
6306
6880
  const enrollment = await registerMachineEnrollment(io, origin, humanCred, keys, humanRef, machine.publicKey);
6307
6881
  io.err(`${enrollment.action === 'noted' ? '!' : '✓'} enrollment: ${enrollment.detail}`);
6308
6882
  steps.push(enrollment);
6309
- // --- [5/7] owenloop settings ---
6310
- io.err('[5/7] owenloop settings');
6883
+ // --- [5/8] owenloop settings ---
6884
+ io.err('[5/8] owenloop settings');
6311
6885
  const settingsPath = owenloopSettingsPath(io.env);
6312
6886
  const existingSettings = readOwenloopSettingsRaw(settingsPath); // corrupt file → hard CliError (never clobber)
6313
6887
  const currentHub = existingSettings && typeof existingSettings.hubOrigin === 'string' ? existingSettings.hubOrigin : undefined;
@@ -6323,16 +6897,40 @@ async function dispatchSetup(io, args) {
6323
6897
  if (agentAccount !== 'default') {
6324
6898
  io.err(`non-default agent account — run owenloop work with OWENLOOP_ACCOUNT=${agentAccount}`);
6325
6899
  }
6326
- // --- [6/7] plugin (non-fatal) ---
6327
- io.err('[6/7] plugin');
6900
+ // --- [6/8] crew rosters ---
6901
+ io.err('[6/8] crew rosters');
6902
+ if (agentCrews === undefined || agentCrews.length === 0) {
6903
+ const detail = 'no crews known for this agent';
6904
+ io.err(`! crew rosters: ${detail}`);
6905
+ steps.push({ step: 'crew rosters', action: 'noted', detail });
6906
+ }
6907
+ else {
6908
+ for (const crew of agentCrews) {
6909
+ const path = crewRosterPath(io.env, crew);
6910
+ // Write a complete private temp first, then install it with link(2): the
6911
+ // link is exclusive (EEXIST leaves an operator file untouched), while a
6912
+ // short write can only leave a removable temp, never a corrupt roster.
6913
+ const installed = installCrewRosterIfAbsent(path, `${JSON.stringify({ crew, note: `machine-local overrides for crew ${crew}; wins over settings.json and hub rosters — see docs/cli.md`, roster: {} }, null, 2)}\n`);
6914
+ if (installed === 'created') {
6915
+ io.err(`✓ crew roster ${crew}: created`);
6916
+ steps.push({ step: 'crew rosters', action: 'done', detail: `${crew}: ${path}` });
6917
+ }
6918
+ else {
6919
+ io.err(`✓ crew roster ${crew}: existing file left untouched`);
6920
+ steps.push({ step: 'crew rosters', action: 'skipped', detail: `${crew}: ${path}` });
6921
+ }
6922
+ }
6923
+ }
6924
+ // --- [7/8] plugin (non-fatal) ---
6925
+ io.err('[7/8] plugin');
6328
6926
  for (const pluginState of probePlugin(io)) {
6329
6927
  const outcome = installPluginStep(io, pluginState);
6330
6928
  const marker = outcome.action === 'noted' ? '!' : '✓';
6331
6929
  io.err(`${marker} plugin (${pluginState.id}): ${outcome.detail}`);
6332
6930
  steps.push({ step: `plugin (${pluginState.id})`, ...outcome });
6333
6931
  }
6334
- // --- [7/7] doctor pass ---
6335
- io.err('[7/7] doctor');
6932
+ // --- [8/8] doctor pass ---
6933
+ io.err('[8/8] doctor');
6336
6934
  const doctor = await runDoctor(io, origin);
6337
6935
  print(io, { ok: doctor.ok, hub: origin, steps, doctor: { ok: doctor.ok, checks: doctor.checks } });
6338
6936
  return doctor.ok ? 0 : 1;
@@ -6526,35 +7124,38 @@ async function runDoctor(io, origin) {
6526
7124
  record('owenloop settings', true, settingsPath, true);
6527
7125
  }
6528
7126
  }
6529
- // Crew-roster diagnostics are informational per crew. The same registry
6530
- // membership predicate the worker uses is intentionally reused here.
7127
+ // Crew-roster diagnostics are informational per crew. Global disk discovery
7128
+ // complements the verified agent's authoritative crew list: a malformed
7129
+ // bounded-hash file cannot decode its own identity, but the worker still
7130
+ // resolves that requested deterministic target and must fail closed on it.
7131
+ const crewNames = new Set();
6531
7132
  try {
6532
- const crewsDir = join(owenloopConfigDir(io.env), 'crews');
6533
- const crews = existsSync(crewsDir)
6534
- ? readdirSync(crewsDir, { withFileTypes: true })
6535
- .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
6536
- .map((entry) => entry.name.slice(0, -'.json'.length))
6537
- .sort()
6538
- : [];
6539
- for (const crew of crews) {
6540
- try {
6541
- const layers = machineRosterLayers(io.env, crew);
6542
- const merged = mergeRosterLayers(layers);
6543
- const found = layers
6544
- .map((layer) => `${layer.source}=${layer.roster === undefined ? 'absent' : 'found'}`)
6545
- .join(', ');
6546
- const harnesses = [...new Set(Object.values(merged).flatMap((entry) => entry.candidates.map((candidate) => candidate.harness)))];
6547
- const present = harnesses.filter((id) => adapterFor(id) !== undefined);
6548
- const missing = harnesses.filter((id) => adapterFor(id) === undefined);
6549
- record(`crew roster (${crew})`, true, `layers: ${found}; harnesses present: ${present.join(', ') || 'none'}; missing: ${missing.join(', ') || 'none'}`, false);
6550
- }
6551
- catch (error) {
6552
- record(`crew roster (${crew})`, false, error instanceof Error ? error.message : String(error), false);
6553
- }
6554
- }
7133
+ for (const file of discoverCrewRosterFiles(io.env))
7134
+ crewNames.add(file.crew);
6555
7135
  }
6556
7136
  catch (error) {
6557
- record('crew roster', false, error instanceof Error ? error.message : String(error), false);
7137
+ record('crew roster discovery', false, error instanceof Error ? error.message : String(error), false);
7138
+ }
7139
+ if (agentProbe.verified?.identity !== undefined) {
7140
+ for (const crew of agentProbe.verified.identity.crews)
7141
+ crewNames.add(crew);
7142
+ }
7143
+ for (const crew of [...crewNames].sort()) {
7144
+ try {
7145
+ const settings = loadSettings(io.env);
7146
+ const layers = effectiveRosterLayers(io.env, crew, { origin: settings.hubOrigin, account: io.env.OWENLOOP_ACCOUNT ?? 'default' });
7147
+ const merged = mergeRosterLayers(layers);
7148
+ const found = layers
7149
+ .map((layer) => `${layer.source}=${layer.roster === undefined ? 'absent' : 'found'}`)
7150
+ .join(', ');
7151
+ const harnesses = [...new Set(Object.values(merged).flatMap((entry) => entry.candidates.map((candidate) => candidate.harness)))];
7152
+ const present = harnesses.filter((id) => adapterFor(id) !== undefined);
7153
+ const missing = harnesses.filter((id) => adapterFor(id) === undefined);
7154
+ record(`crew roster (${crew})`, true, `layers: ${found}; harnesses present: ${present.join(', ') || 'none'}; missing: ${missing.join(', ') || 'none'}`, false);
7155
+ }
7156
+ catch (error) {
7157
+ record(`crew roster (${crew})`, false, error instanceof Error ? error.message : String(error), false);
7158
+ }
6558
7159
  }
6559
7160
  // plugins (rendered; non-core while PLUGIN_CHECK_FATAL is false)
6560
7161
  for (const pluginState of probePlugin(io)) {
@@ -6587,18 +7188,22 @@ async function runDoctor(io, origin) {
6587
7188
  * the async path, so every existing command and test keeps working exactly as
6588
7189
  * before.
6589
7190
  */
6590
- export const ASYNC_COMMANDS = new Set(['add', 'login', 'logout', 'connect', 'publish', 'trust', 'push', 'start', 'cancel', 'instance', 'agent', 'capability', 'routing', 'crew', 'setup', 'doctor', 'enrollments', 'mcp', 'shift']);
7191
+ export const ASYNC_COMMANDS = new Set(['add', 'login', 'logout', 'connect', 'publish', 'trust', 'push', 'start', 'cancel', 'retry', 'instance', 'agent', 'capability', 'routing', 'crew', 'roster', 'setup', 'doctor', 'enrollments', 'mcp', 'shift']);
6591
7192
  export async function mainAsync(argv, io = defaultIO()) {
6592
7193
  // Delegate execution-side and shift argv tails before root parsing. Their
6593
7194
  // roles own their option grammars, including repeated/value forms that the
6594
7195
  // engine parser must not consume. These dynamic imports are cold-start
6595
7196
  // boundaries: ordinary root commands never evaluate execution adapters.
6596
- if (argv[0] === 'work' || argv[0] === 'shift') {
7197
+ if (argv[0] === 'work' || argv[0] === 'shift' || argv[0] === 'util') {
6597
7198
  try {
6598
7199
  if (argv[0] === 'work') {
6599
7200
  const { mainAsync: runWork } = await import("../packages/work/src/main.js");
6600
7201
  return await runWork(argv.slice(1));
6601
7202
  }
7203
+ if (argv[0] === 'util') {
7204
+ const { mainAsync: runWork } = await import("../packages/work/src/main.js");
7205
+ return await runWork(['util', ...argv.slice(1)]);
7206
+ }
6602
7207
  const { run: runShift } = await import("../packages/work/src/roles/shift.js");
6603
7208
  return await runShift(argv.slice(1));
6604
7209
  }
@@ -6635,6 +7240,11 @@ export async function mainAsync(argv, io = defaultIO()) {
6635
7240
  return await dispatchStart(io, args);
6636
7241
  case 'cancel':
6637
7242
  return await dispatchCancel(io, args);
7243
+ case 'retry':
7244
+ // Local engine store unless --hub; only the hub half is async, and
7245
+ // main()'s own `case 'retry'` stays the local implementation so the
7246
+ // synchronous callers of main() keep working.
7247
+ return args.options.has('hub') ? await dispatchRetry(io, args) : main(argv, io);
6638
7248
  case 'instance':
6639
7249
  return await dispatchInstance(io, args);
6640
7250
  case 'agent':
@@ -6645,6 +7255,8 @@ export async function mainAsync(argv, io = defaultIO()) {
6645
7255
  return await dispatchRouting(io, args);
6646
7256
  case 'crew':
6647
7257
  return await dispatchCrew(io, args);
7258
+ case 'roster':
7259
+ return await dispatchRoster(io, args);
6648
7260
  case 'setup':
6649
7261
  return await dispatchSetup(io, args);
6650
7262
  case 'doctor':