overlord-cli 0.2605310708.0 → 0.2605312007.0

package/README.md

@@ -149,10 +149,11 @@ Agents can find docs here: https://www.ovld.ai/docs/for-agents
 - `get-device` / `update-device` - register the caller machine (per organization + user + fingerprint) and rename its label
 - `list-project-resources` / `add-project-resource` / `update-project-resource` - manage filesystem directories tied to a project device
 - `request-execution` / `claim-execution` / `complete-execution-launch` / `fail-execution-launch` - durable runner queue operations used by auto-advance and manual Run
+- `list-organizations` - list every organization the authenticated user (or agent token) belongs to; the runner uses this to poll all of your organizations, not just the one stored at login
 
 Devices are keyed by **(organization, user, fingerprint)** so the same physical workstation can appear once per org session.
 
-`ovld runner start` keeps a foreground runner alive for CLI-only or remote hosts. It claims compatible execution requests for the current device and launches the assigned agent/model with `ovld launch`; `ovld runner once` claims at most one request and exits.
+`ovld runner start` keeps a foreground runner alive for CLI-only or remote hosts. It claims compatible execution requests for the current device and launches the assigned agent/model with `ovld launch`; `ovld runner once` claims at most one request and exits. By default a single runner drains queued requests from **every organization you belong to**, so you do not need one runner per org. Pin it to a single org with `--organization-id <id>` or `OVERLORD_ORGANIZATION_ID`.
 
 Use `create` for future work you want to track, `prompt` for work that should start immediately, and `record-work` for work that was already completed in chat and now needs a review ticket plus feed post. Use multiple tickets when prompts represent different features or goals; use `add-objectives` or `--objectives-json '[{"objective":"Step one"},{"objective":"Step two"}]'` when prompts are sequential steps toward the same feature or goal.
 

package/bin/_cli/protocol.mjs

@@ -2049,6 +2049,24 @@ async function protocolClaimExecution(args) {
   console.log(JSON.stringify(data, null, 2));
 }
 
+async function protocolListOrganizations(args) {
+  const flags = parseFlags(args);
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags);
+  const timeoutMs = resolveTimeout(flags);
+
+  const data = await apiPost(
+    platformUrl,
+    bearerToken,
+    localSecret,
+    organizationId,
+    '/api/protocol/organizations',
+    {},
+    timeoutMs
+  );
+  console.log(JSON.stringify(data, null, 2));
+}
+
 async function protocolCompleteExecutionLaunch(args) {
   const flags = parseFlags(args);
   const { platformUrl, bearerToken, localSecret, organizationId } =
@@ -2644,6 +2662,7 @@ Subcommands:
   request-approval-gate     Flip auto_advance=false on the next queued future objective
   request-execution         Queue an objective for local/remote runner execution
   claim-execution           Claim one queued execution request for this device
+  list-organizations        List organizations the authenticated user belongs to
   complete-execution-launch Mark a claimed execution request launched
   fail-execution-launch     Mark a claimed execution request failed
   permission-request        Notify Overlord that the agent is requesting tool permission
@@ -3139,6 +3158,12 @@ claim-execution:
     --lease-seconds <n>
     --project-id <uuid>
 
+list-organizations:
+  Purpose:
+    Print every organization the authenticated user (or agent token) belongs to.
+    The runner uses this to poll all of your organizations, not just the one
+    stored at login. Takes no required flags.
+
 complete-execution-launch:
   Required:
     --request-id <uuid>        (or EXECUTION_REQUEST_ID env var)
@@ -3184,6 +3209,7 @@ Examples:
   ovld protocol attachment-download-url --session-key <key> --attachment-id <attachment-id>
   ovld protocol request-execution --ticket-id 1:899 --agent codex --requested-from manual_run
   ovld protocol claim-execution --device-fingerprint $OVERLORD_DEVICE_FINGERPRINT
+  ovld protocol list-organizations
   ovld protocol deliver --session-key <key> --ticket-id <ticket_id> --summary "Done"
   ovld protocol deliver --session-key <key> --ticket-id <ticket_id> --summary "Done" --artifacts-file ./artifacts.json
   ovld protocol deliver --session-key <key> --ticket-id <ticket_id> --payload-json '{"summary":"Done","artifacts":[{"type":"note","label":"Delivery","content":"..."}]}'
@@ -3303,6 +3329,10 @@ EOF
     await protocolClaimExecution(args);
     return;
   }
+  if (subcommand === 'list-organizations') {
+    await protocolListOrganizations(args);
+    return;
+  }
   if (subcommand === 'complete-execution-launch') {
     await protocolCompleteExecutionLaunch(args);
     return;

package/bin/_cli/runner.mjs

@@ -27,8 +27,12 @@ Options:
   --device-fingerprint <fp>  Override runner device identity
   --poll-interval-ms <ms>    Poll interval for start mode (default 3000)
   --project-id <uuid>        Only claim requests for one project
+  --organization-id <id>     Only poll one organization (also OVERLORD_ORGANIZATION_ID).
+                             Default: poll every organization you belong to.
 
 The runner claims durable execution requests and launches them with \`${primaryCommand} launch\`.
+By default it drains queued requests from all of your organizations, so a single
+runner serves every org without needing one instance per org.
 `);
 }
 
@@ -89,7 +93,7 @@ function protocolJson(subcommand, args, env) {
   return stdout.trim() ? JSON.parse(stdout) : {};
 }
 
-function claimExecution(flags, deviceFingerprint) {
+function claimExecution(flags, deviceFingerprint, organizationId) {
   const args = [
     '--device-fingerprint',
     deviceFingerprint,
@@ -98,12 +102,82 @@ function claimExecution(flags, deviceFingerprint) {
     '--device-platform',
     process.platform
   ];
+  // An explicit organization id scopes this claim to one org. The CLI turns it
+  // into the `x-organization-id` header, which OAuth-authenticated protocol
+  // requests require and the server validates against the user's membership.
+  if (organizationId) {
+    args.push('--organization-id', String(organizationId));
+  }
   if (typeof flags['project-id'] === 'string') {
     args.push('--project-id', flags['project-id']);
   }
   return protocolJson('claim-execution', args, { OVERLORD_DEVICE_FINGERPRINT: deviceFingerprint });
 }
 
+function listOrganizationIds(deviceFingerprint) {
+  const data = protocolJson('list-organizations', [], {
+    OVERLORD_DEVICE_FINGERPRINT: deviceFingerprint
+  });
+  const organizations = Array.isArray(data.organizations) ? data.organizations : [];
+  return organizations
+    .map(organization => organization?.id)
+    .filter(id => Number.isInteger(id) && id > 0)
+    .map(id => String(id));
+}
+
+function resolvePinnedOrganizationId(flags) {
+  const fromFlag =
+    typeof flags['organization-id'] === 'string' ? flags['organization-id'].trim() : '';
+  if (fromFlag) return fromFlag;
+  const fromEnv = process.env.OVERLORD_ORGANIZATION_ID?.trim();
+  return fromEnv || '';
+}
+
+// Re-discover the user's organizations periodically so a runner picks up newly
+// joined orgs without a restart, without hitting the API on every poll.
+const ORGANIZATION_REFRESH_MS = 60_000;
+
+/**
+ * Resolves which organizations a poll pass should claim from.
+ *
+ * - When the user pins an org (`--organization-id` flag or
+ *   `OVERLORD_ORGANIZATION_ID`), only that org is polled.
+ * - Otherwise the runner discovers every org the authenticated user belongs to
+ *   and polls each one. If discovery fails or returns nothing, it falls back to
+ *   the credential default (an empty scope id) so behavior never regresses.
+ */
+export function createOrganizationScope(flags, deviceFingerprint) {
+  const pinned = resolvePinnedOrganizationId(flags);
+  if (pinned) {
+    return { pinned: true, resolve: () => [pinned] };
+  }
+
+  let cache = [];
+  let fetchedAt = 0;
+  return {
+    pinned: false,
+    resolve() {
+      const now = Date.now();
+      if (cache.length === 0 || now - fetchedAt >= ORGANIZATION_REFRESH_MS) {
+        try {
+          const ids = listOrganizationIds(deviceFingerprint);
+          fetchedAt = now;
+          // Keep the last known good list on a transient empty result.
+          if (ids.length > 0) cache = ids;
+        } catch (error) {
+          process.stderr.write(
+            `[runner] could not list organizations (${
+              error instanceof Error ? error.message : error
+            }); using the default organization\n`
+          );
+        }
+      }
+      // Empty string = "no override", i.e. the org stored in credentials.
+      return cache.length > 0 ? cache : [''];
+    }
+  };
+}
+
 function completeLaunch(requestId, deviceFingerprint) {
   protocolJson(
     'complete-execution-launch',
@@ -275,11 +349,21 @@ function spawnLaunchProcess(args, claim, deviceFingerprint) {
     runnerTestHooks.platform ?? process.platform
   );
 
+  // Phase 4: thread the execution request id to the launched process so the
+  // agent's `ovld protocol attach` can mark this exact request `launched`.
+  // Attach falls back to matching by objective when this is absent, so this is
+  // a precision aid, not a correctness requirement.
+  const launchEnv = {
+    ...process.env,
+    OVERLORD_DEVICE_FINGERPRINT: deviceFingerprint,
+    ...(claim.request?.id ? { OVERLORD_EXECUTION_REQUEST_ID: claim.request.id } : {})
+  };
+
   if (!terminalCommand) {
     return {
       child: spawnImpl(process.execPath, [OVLD_ENTRY, ...args], {
         stdio: 'inherit',
-        env: { ...process.env, OVERLORD_DEVICE_FINGERPRINT: deviceFingerprint }
+        env: launchEnv
       }),
       completeOnClose: false
     };
@@ -288,7 +372,7 @@ function spawnLaunchProcess(args, claim, deviceFingerprint) {
   return {
     child: spawnImpl('sh', ['-lc', terminalCommand], {
       stdio: 'inherit',
-      env: { ...process.env, OVERLORD_DEVICE_FINGERPRINT: deviceFingerprint }
+      env: launchEnv
     }),
     completeOnClose: true
   };
@@ -348,14 +432,34 @@ export async function launchClaimedRequest(claim, deviceFingerprint) {
   return true;
 }
 
-export async function runOnce(flags, deviceFingerprint) {
-  const claim = claimExecution(flags, deviceFingerprint);
-  if (!claim.request) {
+export async function runOnce(flags, deviceFingerprint, organizationScope) {
+  const scope = organizationScope ?? createOrganizationScope(flags, deviceFingerprint);
+  const organizationIds = scope.resolve();
+
+  let launchedAny = false;
+  for (const organizationId of organizationIds) {
+    let claim;
+    try {
+      claim = claimExecution(flags, deviceFingerprint, organizationId);
+    } catch (error) {
+      // A single organization failing (transient API/auth error) must not stop
+      // the runner from servicing the others.
+      process.stderr.write(
+        `[runner] claim failed for organization ${organizationId || 'default'}: ${
+          error instanceof Error ? error.message : error
+        }\n`
+      );
+      continue;
+    }
+    if (!claim.request) continue;
+    await launchClaimedRequest(claim, deviceFingerprint);
+    launchedAny = true;
+  }
+
+  if (!launchedAny) {
     process.stderr.write('[runner] no queued execution requests\n');
-    return false;
   }
-  await launchClaimedRequest(claim, deviceFingerprint);
-  return true;
+  return launchedAny;
 }
 
 function sleep(ms) {
@@ -398,10 +502,18 @@ export async function runRunnerCommand(subcommand, args, primaryCommand = 'ovld'
       typeof flags['poll-interval-ms'] === 'string'
         ? Math.max(1000, Number.parseInt(flags['poll-interval-ms'], 10) || 3000)
         : 3000;
+    // Build the organization scope once so its discovery cache persists across
+    // polls instead of refetching the org list every iteration.
+    const organizationScope = createOrganizationScope(flags, deviceFingerprint);
     process.stderr.write(`[runner] started with device ${deviceFingerprint}\n`);
+    process.stderr.write(
+      organizationScope.pinned
+        ? `[runner] polling a single organization\n`
+        : `[runner] polling every organization you belong to\n`
+    );
     for (;;) {
       try {
-        const launched = await runOnce(flags, deviceFingerprint);
+        const launched = await runOnce(flags, deviceFingerprint, organizationScope);
         if (!launched) await sleep(pollIntervalMs);
       } catch (error) {
         process.stderr.write(`[runner] ${error instanceof Error ? error.message : error}\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "overlord-cli",
-  "version": "0.2605310708.0",
+  "version": "0.2605312007.0",
   "description": "Overlord CLI — launch AI agents on tickets from anywhere",
   "homepage": "https://www.ovld.ai/docs/",
   "type": "module",