feat: require titles for hosted runs (#1022)

## What

- require `--title` for private hosted `zeroshot run --target`
submissions
- validate titles as 1–100 Unicode characters and preserve them across
exact-key retries
- send the title through the existing RunIntent `label` field for Zero
Cloud display
- keep the stable/public CLI surface unchanged

## Why

Cloud runs currently arrive with the hardcoded label `zeroshot-cli`, so
operators cannot identify them in the dashboard.

## Impact

Private hosted callers must now pass `--title <title>`. The Zero Cloud
wire contract remains unchanged because `label` already exists and is
persisted/displayed end to end.

## Checks

- `npm run test` — 3,001 passing, 17 pending
- `npm run test:hosted` — 61 private candidate tests and 44
hosted-target tests passing
- `npm run lint` — 0 errors (existing warnings only)
- touched-file Prettier check — passing
- `opcore check --changed` — passing
- `opcore-zero check --staged` — clean
- Opcore Zero Sense reported no introduced cycles, duplicates, or
interface findings; its repository-wide duplicate scan remained
incomplete at the configured resource bound

Co-authored-by: Michael Eichelbeck <michael@theopenengine.com>

Author: mkceichelbeck

private/hosted-cli-candidate/README.md

@@ -3,9 +3,10 @@
 This guide applies only to the unpublished private candidate. The public Zeroshot package does not
 contain these commands, this guide, or the accompanying examples.
 
-A remote run has four inputs:
+A remote run has five inputs:
 
 - A **target** names the remote Zeroshot service and holds your authenticated session.
+- A **title** of 1 to 100 Unicode characters identifies the run in Zeroshot Cloud.
 - A **runtime config** selects the model API, Zeroshot harness, model, credentials, and normal
   Zeroshot settings.
 - The supplied **graph** is the candidate's fixed delivery contract. The **input** contains the work
@@ -69,6 +70,7 @@ Start a run with Zeroshot's built-in coordinator by omitting `--config`:
 ```bash
 zeroshot run \
   --target team \
+  --title 'Review checkout flow' \
   --graph examples/graph.json \
   --input examples/input.json \
   --ship
@@ -153,6 +155,7 @@ control the agent topology, pass a declarative Zeroshot cluster config:
 ```bash
 zeroshot run \
   --target team \
+  --title 'Review checkout flow' \
   --graph examples/graph.json \
   --input examples/input.json \
   --config examples/cluster.json \
@@ -182,10 +185,10 @@ zeroshot list --target team
 
 If submission ended without a definite response, the error includes the submission key that was
 printed before the request. The key is an idempotency key, not a lookup: retry only when the fully
-resolved request is unchanged. That means the graph, input, custom cluster, runtime file and its
-referenced environment values and files, GitHub token, size, delivery mode, and resolved repository
-revision must all match the first request. A changed request with the same key is rejected rather
-than creating a second run.
+resolved request is unchanged. That means the title, graph, input, custom cluster, runtime file and
+its referenced environment values and files, GitHub token, size, delivery mode, and resolved
+repository revision must all match the first request. A changed request with the same key is
+rejected rather than creating a second run.
 
 For a recoverable run, configure an exact commit base and keep all referenced inputs unchanged
 until submission is confirmed. Then repeat the exact run with the canonical UUID as
@@ -195,6 +198,7 @@ ask the target operator to determine whether the original request was accepted.
 ```bash
 zeroshot run \
   --target team \
+  --title 'Review checkout flow' \
   --graph examples/graph.json \
   --input examples/input.json \
   --ship \
@@ -205,6 +209,7 @@ zeroshot run \
 
 - Remote runs accept explicit JSON graph and input files; general text or issue positionals remain
   local-only.
+- Remote runs require `--title`; Zeroshot Cloud displays the value without rewriting it.
 - The remote graph is the included single-worker delivery graph with one attempt; keep it unchanged.
 - Remote delivery always uses `--pr` or `--ship`; there is no delivery-free remote run.
 - `logs --target`, the `ls` alias with `--target`, and cross-target listing are not available.

private/hosted-cli-candidate/default-run-intent-services.js

@@ -34,8 +34,8 @@ function isDeterministicSubmissionError(error) {
 function submissionUncertain(submissionKey, cause) {
   return new Error(
     'RunIntent submission outcome is uncertain. Do not create a replacement. ' +
-      'Retry only if the graph, input, cluster config, runtime references, credentials, size, ' +
-      'delivery mode, and resolved repository revision are unchanged. ' +
+      'Retry only if the title, graph, input, cluster config, runtime references, credentials, ' +
+      'size, delivery mode, and resolved repository revision are unchanged. ' +
       `Then rerun with --submission-key ${submissionKey}; a changed payload is rejected.`,
     { cause }
   );
@@ -211,6 +211,7 @@ async function submitRun(service, options, prepared, signal) {
       envelope: buildRunIntentEnvelope(execution.graph, execution.input),
       runtime,
       submissionKey,
+      title: options.title,
       ...(options.size === undefined ? {} : { size: options.size }),
       signal,
     });

private/hosted-cli-candidate/help-text.js

@@ -5,7 +5,7 @@ Workflow:
   1. zeroshot target add <name> --url <https-origin>
   2. zeroshot target login <name>
   3. zeroshot target setup <name> --repository <owner/name> --runtime-config <file>
-  4. zeroshot run --target <name> --graph <file> --input <file> --ship
+  4. zeroshot run --target <name> --title <title> --graph <file> --input <file> --ship
 
 Run \`zeroshot target <command> --help\` for command details.
 `;
@@ -22,6 +22,7 @@ The runtime file is read for every run. Setup stores its path, not resolved secr
 `;
 const HOSTED_RUN_HELP = `
 Remote execution with --target:
+  --title is required and is shown in Zeroshot Cloud.
   --graph and --input are required explicit JSON files.
   Keep the candidate graph unchanged; put the work request in the input.
   --pr or --ship is required for Git delivery.
@@ -31,8 +32,8 @@ Remote execution with --target:
   --submission-key retries only an unchanged, fully resolved request.
 
 Examples:
-  zeroshot run --target team --graph graph.json --input input.json --ship
-  zeroshot run --target team --graph graph.json --input input.json --config cluster.json --ship
+  zeroshot run --target team --title "Review" --graph graph.json --input input.json --ship
+  zeroshot run --target team --title "Review" --graph graph.json --input input.json --config cluster.json --ship
 `;
 
 module.exports = { HOSTED_RUN_HELP, TARGET_HELP, TARGET_SETUP_HELP };

private/hosted-cli-candidate/manifest.js

@@ -12,7 +12,7 @@ const COMMAND_MANIFEST = Object.freeze([
   'target cancel <name> <intent-id>',
   'capsule create --target <name> [--label <label>] [--size <size>]',
   'capsule terminate <capsule-id> --target <name>',
-  'run --graph <graph.json> --input <input.json> --target <name> (--pr|--ship) ' +
+  'run --title <title> --graph <graph.json> --input <input.json> --target <name> (--pr|--ship) ' +
     '[--config <cluster.json>] [--size <size>] [--submission-key <uuid>] [-d]',
   'attach <intent-id> --target <name>',
   'list --target <name> [--limit <n>] [--json]',

private/hosted-cli-candidate/register.js

@@ -22,6 +22,7 @@ const HOSTED_RUN_OPTIONS = new Set([
   'detach',
   'submissionKey',
   'size',
+  'title',
   'pr',
   'ship',
   'config',
@@ -121,6 +122,7 @@ function registerHostedRun(program, service) {
     .option('--graph <file>', 'Candidate delivery GraphSpec JSON')
     .option('--input <file>', 'Explicit hosted JSON input')
     .option('--target <name>', 'Named private hosted target')
+    .option('--title <title>', 'Run title shown in Zeroshot Cloud')
     .option('--size <size>', 'Advertised capsule size')
     .option(
       '--submission-key <uuid>',
@@ -135,11 +137,12 @@ function registerHostedRun(program, service) {
         options.graph !== undefined ||
         options.input !== undefined ||
         options.size !== undefined ||
-        options.submissionKey !== undefined
+        options.submissionKey !== undefined ||
+        options.title !== undefined
       ) {
         return failClosed(() =>
           Promise.reject(
-            new Error('--graph, --input, --size, and --submission-key require --target')
+            new Error('--graph, --input, --size, --submission-key, and --title require --target')
           )
         );
       }
@@ -178,6 +181,10 @@ function validateHostedRunInput(options) {
   if (!options.graph || !options.input) {
     throw new Error('hosted run requires both --graph and --input');
   }
+  const characters = typeof options.title === 'string' ? Array.from(options.title).length : 0;
+  if (characters < 1 || characters > 100) {
+    throw new Error('hosted run title must be between 1 and 100 characters');
+  }
 }
 
 function validateHostedRunDelivery(options) {

private/hosted-cli-candidate/run-intent-http.js

@@ -34,6 +34,14 @@ function serializeOpaqueJson(value, maximum, label) {
   return bytes;
 }
 
+function validatedRunTitle(value) {
+  const characters = typeof value === 'string' ? Array.from(value).length : 0;
+  if (characters < 1 || characters > 100) {
+    throw new RunIntentRequestError('RunIntent title must be between 1 and 100 characters');
+  }
+  return value;
+}
+
 class RunIntentHttpError extends Error {
   constructor(status) {
     super(`RunIntent request failed with HTTP ${status}`);
@@ -145,8 +153,9 @@ class RunIntentClient {
     this.#fetch = options.fetch;
   }
 
-  submit({ envelope, runtime, submissionKey, size, signal }) {
+  submit({ envelope, runtime, submissionKey, size, title, signal }) {
     assertUuid(submissionKey, 'submission key');
+    const label = validatedRunTitle(title);
     if (size !== undefined && !['tiny', 'small', 'standard', 'large'].includes(size)) {
       throw new RunIntentRequestError('RunIntent size is invalid');
     }
@@ -162,7 +171,7 @@ class RunIntentClient {
       throw new RunIntentRequestError('RunIntent payloads exceed the decoded dispatch size bound');
     }
     const body = encodeBoundedJson({
-      label: 'zeroshot-cli',
+      label,
       ...(size === undefined ? {} : { size }),
       intent: intentBytes.toString('base64url'),
       runtime: runtimeBytes.toString('base64url'),

tests/private-hosted-cli/candidate-fixtures.js

@@ -83,6 +83,7 @@ function detachedRunOptions(submissionKey, overrides = {}) {
     target: 'prod',
     graph: 'graph.json',
     input: 'input.json',
+    title: 'Review checkout flow',
     submissionKey,
     detach: true,
     ...overrides,

tests/private-hosted-cli/parser.test.js

@@ -6,6 +6,8 @@ const { afterEach, describe, it } = require('node:test');
 const { COMMAND_MANIFEST } = require('../../private/hosted-cli-candidate/manifest');
 const { registerPrivateHostedCandidate } = require('../../private/hosted-cli-candidate/register');
 
+const RUN_TITLE = 'Review checkout flow';
+
 function harness() {
   const calls = [];
   const program = new Command();
@@ -76,7 +78,18 @@ async function parse(program, argv) {
 }
 
 function hostedRun(...options) {
-  return ['run', '--target', 'prod', '--graph', 'g.json', '--input', 'i.json', ...options];
+  return [
+    'run',
+    '--target',
+    'prod',
+    '--graph',
+    'g.json',
+    '--input',
+    'i.json',
+    '--title',
+    RUN_TITLE,
+    ...options,
+  ];
 }
 
 afterEach(() => {
@@ -122,12 +135,35 @@ async function rejectsGeneralTextRunWithTarget() {
     'g.json',
     '--input',
     'i.json',
+    '--title',
+    RUN_TITLE,
     '--pr',
   ]);
   assert.deepEqual(calls, []);
   assert.equal(process.exitCode, 1);
 }
 
+async function requiresBoundedHostedRunTitles() {
+  for (const argv of [
+    ['run', '--target', 'prod', '--graph', 'g.json', '--input', 'i.json', '--ship'],
+    hostedRun('--title', '', '--ship'),
+    hostedRun('--title', '🚀'.repeat(101), '--ship'),
+    ['run', 'local-task', '--title', RUN_TITLE],
+  ]) {
+    const rejected = harness();
+    await parse(rejected.program, argv);
+    assert.deepEqual(rejected.calls, []);
+    assert.equal(process.exitCode, 1);
+    process.exitCode = 0;
+  }
+
+  const accepted = harness();
+  const title = '🚀'.repeat(100);
+  await parse(accepted.program, hostedRun('--title', title, '--ship'));
+  assert.equal(accepted.calls[0][0], 'remoteRun');
+  assert.equal(accepted.calls[0][1].title, title);
+}
+
 async function usesOnlyRunIntentAndKeepsRecoverySyntax() {
   const runIntent = harness();
   await parse(
@@ -196,6 +232,7 @@ async function dispatchesRemoteLifecycleRoutes() {
   );
   assert.equal(calls[3][2].force, true);
   assert.equal(calls[0][1].config, 'cluster.json');
+  assert.equal(calls[0][1].title, RUN_TITLE);
 }
 
 async function exposesPrivateTargetRunIntentRoutes() {
@@ -238,6 +275,7 @@ function registerPrivateCandidateParserTests() {
     ],
     ['rejects incompatible hosted run syntax', rejectsIncompatibleHostedRunSyntax],
     ['rejects general text run with a target', rejectsGeneralTextRunWithTarget],
+    ['requires bounded hosted run titles', requiresBoundedHostedRunTitles],
     ['uses only RunIntent and keeps recovery syntax', usesOnlyRunIntentAndKeepsRecoverySyntax],
     ['rejects empty targets and hosted ls aliases', rejectsEmptyTargetsAndHostedLsAliases],
     ['preserves local ls after a global option', preservesLocalLsAliasAfterGlobalOption],

tests/private-hosted-cli/run-intent-client.test.js

@@ -25,6 +25,7 @@ const ORGANIZATION_ID = '019fd17e-5e50-7c66-a68c-3fcf4d8f06c0';
 const SUBMISSION_KEY = '019fd17e-8406-41b4-8730-1c54fd44c70e';
 const CAPSULE_ID = '019fd17e-b9c4-7ef1-99da-cc0ef3905402';
 const OTHER_INTENT_ID = '019fd184-52c3-7e1f-a567-4ecb6fc6a0ec';
+const RUN_TITLE = 'Review checkout flow';
 
 function jsonResponse(value, status = 200) {
   return new globalThis.Response(JSON.stringify(value), {
@@ -85,6 +86,7 @@ describe('bounded authenticated RunIntent client', () => {
       runtime: RUNTIME_BUNDLE,
       submissionKey: SUBMISSION_KEY,
       size: 'standard',
+      title: RUN_TITLE,
     });
     assert.equal(result.intent_id, INTENT_ID);
     assert.equal(h.requests.length, 1);
@@ -95,7 +97,7 @@ describe('bounded authenticated RunIntent client', () => {
     assert.equal(request.init.headers['idempotency-key'], SUBMISSION_KEY);
     const wrapper = JSON.parse(request.init.body);
     assert.deepEqual(Object.keys(wrapper), ['label', 'size', 'intent', 'runtime']);
-    assert.equal(wrapper.label, 'zeroshot-cli');
+    assert.equal(wrapper.label, RUN_TITLE);
     assert.equal(wrapper.size, 'standard');
     for (const field of ['intent', 'runtime']) {
       assert.match(wrapper[field], /^[A-Za-z0-9_-]+$/);
@@ -170,14 +172,39 @@ describe('bounded RunIntent authentication and bodies', () => {
 });
 
 describe('opaque RunIntent submit serialization', () => {
+  it('requires a title of at most 100 Unicode characters before sending', async () => {
+    for (const title of [undefined, '', 'x'.repeat(101), '🚀'.repeat(101)]) {
+      const rejected = clientHarness([]);
+      assert.throws(
+        () =>
+          rejected.client.submit({
+            envelope: {},
+            runtime: {},
+            submissionKey: SUBMISSION_KEY,
+            title,
+          }),
+        /title must be between 1 and 100 characters/
+      );
+      assert.equal(rejected.requests.length, 0);
+    }
+    const accepted = clientHarness([jsonResponse(runIntent(), 202)]);
+    const title = '🚀'.repeat(100);
+    await accepted.client.submit({
+      envelope: {},
+      runtime: {},
+      submissionKey: SUBMISSION_KEY,
+      title,
+    });
+    assert.equal(JSON.parse(accepted.requests[0].init.body).label, title);
+  });
   it('omits capsule size when the caller preserves the target default', async () => {
     const h = clientHarness([jsonResponse(runIntent(), 202)]);
     await h.client.submit({
       envelope: buildRunIntentEnvelope(GRAPH, { source: 'prompt' }),
       runtime: RUNTIME_BUNDLE,
       submissionKey: SUBMISSION_KEY,
+      title: RUN_TITLE,
     });
-
     assert.equal(Object.hasOwn(JSON.parse(h.requests[0].init.body), 'size'), false);
   });
 
@@ -199,6 +226,7 @@ describe('opaque RunIntent submit serialization', () => {
         },
       },
       submissionKey: SUBMISSION_KEY,
+      title: RUN_TITLE,
     });
     assert.equal(intentSerializations, 1);
     assert.equal(runtimeSerializations, 1);
@@ -216,6 +244,7 @@ describe('bounded RunIntent submit bodies', () => {
       envelope: intentAtCombinedLimit,
       runtime: runtimeAtLimit,
       submissionKey: SUBMISSION_KEY,
+      title: RUN_TITLE,
     });
     assert.ok(Buffer.byteLength(boundary.requests[0].init.body) <= MAX_RUN_INTENT_REQUEST_BYTES);
 
@@ -226,6 +255,7 @@ describe('bounded RunIntent submit bodies', () => {
           envelope: exactJsonObject(MAX_RUN_INTENT_DISPATCH_BYTES - MAX_RUNTIME_BUNDLE_BYTES - 3),
           runtime: runtimeAtLimit,
           submissionKey: SUBMISSION_KEY,
+          title: RUN_TITLE,
         }),
       /payloads exceed the decoded dispatch size bound/
     );
@@ -239,6 +269,7 @@ describe('bounded RunIntent submit bodies', () => {
           runtime: RUNTIME_BUNDLE,
           submissionKey: SUBMISSION_KEY,
           size: 'standard',
+          title: RUN_TITLE,
         }),
       /intent exceeds the decoded size bound/
     );
@@ -252,6 +283,7 @@ describe('bounded RunIntent submit bodies', () => {
           runtime: exactJsonObject(MAX_RUNTIME_BUNDLE_BYTES + 1),
           submissionKey: SUBMISSION_KEY,
           size: 'standard',
+          title: RUN_TITLE,
         }),
       /runtime bundle exceeds the decoded size bound/
     );