overlord-cli 0.2605300746.0 → 0.2605310708.0

package/README.md

@@ -72,6 +72,7 @@ ovld protocol discover-project --working-directory /path/to/repo --device-finger
 ovld protocol attach --ticket-id <ticket_id>
 ovld protocol search-tickets --query "auth refactor" --status next-up,execute
 ovld protocol update --session-key <session-key> --ticket-id <ticket_id> --summary "Working on it" --phase execute
+ovld protocol heartbeat --session-key <session-key> --ticket-id <ticket_id> --phase execute --percent 50 --note "Running tests"
 ovld runner start
 ovld setup
 ovld setup codex
@@ -133,6 +134,7 @@ Agents can find docs here: https://www.ovld.ai/docs/for-agents
 - `prompt` - create a ticket and attach to it immediately (`spawn` is a backward-compatible alias)
 - `record-work` - record already-completed chat work as a ticket in review with a completed objective and trigger feed-post generation
 - `update` - post progress, discussion/decision events, optional change rationales, and explicit `--begin-follow-up-work` transitions
+- `heartbeat` - send a lightweight liveness ping plus optional transient `phase` / `percent` / `note` telemetry without creating a ticket event
 - `record-change-rationales` - persist structured change rationales without a normal progress update
 - `ask` - post a blocking question and move the ticket to review
 - `permission-request` - notify Overlord that the agent is requesting tool permission
@@ -156,7 +158,7 @@ Use `create` for future work you want to track, `prompt` for work that should st
 
 `ovld protocol deliver` accepts either discrete flags like `--summary` / `--artifacts-json`, an inline full payload with `--payload-json '{"summary":"...","artifacts":[...],"changeRationales":[...]}'`, or a file/stdin payload with `--payload-file <path|->`.
 
-After delivery, follow-up messages are recorded as discussion by default. To start implementation again on a delivered/review ticket, call `ovld protocol update --begin-follow-up-work --follow-up-intent execution --summary "Beginning follow-up work."` before moving back to `--phase execute`. Use `--event-type discussion_summary` or `--event-type decision` for important non-file outcomes. Once follow-up execution records a real work signal, such as an execution update, git snapshot, change rationales, deliverables, or explicit `pending_delivery` intent, Overlord marks the objective `pending_delivery` so redelivery is only required for actual post-delivery work.
+After delivery, follow-up messages are recorded as discussion by default. To start implementation again on a delivered/review ticket, call `ovld protocol update --begin-follow-up-work --follow-up-intent execution --summary "Beginning follow-up work."` before moving back to `--phase execute`. Use `--event-type discussion_summary` or `--event-type decision` for important non-file outcomes. Once follow-up execution records a real work signal, such as an execution update, git snapshot, change rationales, deliverables, or explicit `pending_delivery` intent, Overlord marks the objective `pending_delivery` so redelivery is only required for actual post-delivery work. Use `ovld protocol heartbeat` during long-running mechanical work when you need liveness without adding activity-feed noise.
 
 ## License
 

package/bin/_cli/index.mjs

@@ -54,7 +54,7 @@ Agents:
     installed connector (${primaryCommand} setup <agent>); your custom agents launch by id.
     Anything after a standalone -- is forwarded verbatim to the agent binary.
   Use ${primaryCommand} protocol help for ticket lifecycle commands.
-  Key protocol commands: auth-status, discover-project, create, prompt, attach, connect, load-context.
+  Key protocol commands: auth-status, discover-project, create, prompt, attach, connect, load-context, heartbeat.
 
 Auth:
   ${primaryCommand} auth login               Authorize CLI via browser or --token <oat_…>

package/bin/_cli/protocol.mjs

@@ -1062,6 +1062,56 @@ async function protocolUpdate(args) {
   console.log(JSON.stringify(data, null, 2));
 }
 
+// ---------------------------------------------------------------------------
+// heartbeat
+// ---------------------------------------------------------------------------
+
+async function protocolHeartbeat(args) {
+  const flags = parseFlags(args);
+  const { sessionKey, ticketId } = resolveSessionFlags(flags);
+  if (!sessionKey) throw new Error('--session-key is required (or set SESSION_KEY)');
+  if (!ticketId) throw new Error('--ticket-id is required (or set TICKET_ID)');
+
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags, ticketId);
+  const timeoutMs = resolveTimeout(flags);
+  const externalSessionId = resolveExternalSessionId(flags);
+  const percent =
+    flags.percent !== undefined && flags.percent !== true ? Number(flags.percent) : undefined;
+
+  if (percent !== undefined && (!Number.isFinite(percent) || percent < 0 || percent > 100)) {
+    throw new Error('--percent must be a number between 0 and 100');
+  }
+
+  const body = {
+    sessionKey,
+    ticketId,
+    ...(flags.phase ? { phase: String(flags.phase) } : {}),
+    ...(percent !== undefined ? { percent } : {}),
+    ...(flags.note ? { note: String(flags.note) } : {}),
+    ...(externalSessionId !== undefined ? { externalSessionId } : {}),
+    ...(flags['external-url']
+      ? {
+          externalUrl:
+            String(flags['external-url']).trim().toLowerCase() === 'null'
+              ? null
+              : String(flags['external-url'])
+        }
+      : {})
+  };
+
+  const data = await apiPost(
+    platformUrl,
+    bearerToken,
+    localSecret,
+    organizationId,
+    '/api/protocol/heartbeat',
+    body,
+    timeoutMs
+  );
+  console.log(JSON.stringify(data, null, 2));
+}
+
 // ---------------------------------------------------------------------------
 // record-change-rationales
 // ---------------------------------------------------------------------------
@@ -2588,6 +2638,7 @@ Subcommands:
   prompt                    Create a ticket and attach to it immediately
   record-work               Record completed-from-chat work as a ticket in review + feed post (no attach)
   update                    Post progress, activity events, and optional change rationales
+  heartbeat                 Send a lightweight liveness ping without creating a ticket event
   record-change-rationales  Persist structured change rationales without a progress update
   ask                       Post a blocking question and move the ticket to review
   request-approval-gate     Flip auto_advance=false on the next queued future objective
@@ -2741,6 +2792,23 @@ update:
     Pass --summary-file - to read the summary from stdin — avoids shell interpretation of backticks,
     quotes, or other special characters in the summary text.
 
+heartbeat:
+  Purpose:
+    Send a lightweight liveness ping for an attached session without adding activity-feed noise
+  Required:
+    --session-key <key>
+    --ticket-id <ticket_id>
+  Optional:
+    --phase <status>          draft | execute | review | deliver | complete | blocked | cancelled
+    --percent <0-100>         Optional percent-complete hint for transient UI progress
+    --note <text>             Optional short note, e.g. "Running the integration suite"
+    --external-url <url|null> Store or clear a deep link to the live agent session
+    --external-session-id <id|null>
+  Notes:
+    Heartbeat only updates session liveness plus transient telemetry on the session row.
+    It does not create a ticket event and should be used when you are still working but have
+    nothing meaningful to post via update.
+
 record-change-rationales:
   Purpose:
     Persist structured file-change rationale records without also posting a normal update
@@ -3211,6 +3279,10 @@ EOF
     await protocolUpdate(args);
     return;
   }
+  if (subcommand === 'heartbeat') {
+    await protocolHeartbeat(args);
+    return;
+  }
   if (subcommand === 'record-change-rationales') {
     await protocolRecordChangeRationales(args);
     return;

package/package.json

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

package/plugins/antigravity/scripts/overlord-mcp.mjs

@@ -373,6 +373,40 @@ const tools = [
     }),
     subcommand: 'update'
   },
+  {
+    name: 'heartbeat',
+    description:
+      'Send a lightweight Overlord liveness ping without posting a ticket event. Optional phase/percent/note telemetry is stored on the session row.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session_key: { type: 'string' },
+        ticket_id: {
+          type: 'string',
+          description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.'
+        },
+        phase: {
+          type: 'string',
+          enum: ['draft', 'execute', 'review', 'deliver', 'complete', 'blocked', 'cancelled']
+        },
+        percent: { type: 'number' },
+        note: { type: 'string' },
+        external_url: { type: ['string', 'null'] },
+        external_session_id: { type: ['string', 'null'] }
+      },
+      required: ['session_key', 'ticket_id']
+    },
+    toCliFlags: args => ({
+      'session-key': args.session_key,
+      'ticket-id': args.ticket_id,
+      phase: args.phase,
+      percent: args.percent,
+      note: args.note,
+      'external-url': args.external_url,
+      'external-session-id': args.external_session_id
+    }),
+    subcommand: 'heartbeat'
+  },
   {
     name: 'record_change_rationales',
     description: 'Persist structured change rationale rows without posting a separate update.',

package/plugins/claude/.claude-plugin/plugin.json

@@ -10,7 +10,6 @@
   "repository": "https://github.com/cooperativ/overlord",
   "license": "UNLICENSED",
   "keywords": ["overlord", "tickets", "agents", "workflow", "protocol", "claude-code"],
-  "hooks": "./hooks/hooks.json",
   "userConfig": {
     "overlord_url": {
       "type": "string",

package/plugins/claude/skills/overlord-ticket/SKILL.md

@@ -15,6 +15,7 @@ Use this mode when the prompt already contains a ticket ID or explicitly says th
 2. The attach response prints JSON to stdout containing `session.sessionKey`. The CLI also persists this key automatically so subsequent `ovld protocol` commands in the same working directory resolve it without `--session-key`. If auto-resolution fails, pass `--session-key <sessionKey>` explicitly on every subsequent call.
 3. Treat the Overlord ticket prompt as authoritative for the objective, constraints, and delivery target.
 4. Post updates while working: `ovld protocol update --session-key <sessionKey> --ticket-id <ticket_id> --summary "..." --phase execute`.
+   During long mechanical stretches with nothing meaningful to post, send `ovld protocol heartbeat --session-key <sessionKey> --ticket-id <ticket_id> [--phase execute] [--percent <0-100>] [--note "..."]` instead of an empty update.
 5. Follow-up messages after the initial ticket are captured automatically by the installed `UserPromptSubmit` hook and stay in discussion intent while the ticket is in review. Do not post `user_follow_up` manually unless the hook is unavailable.
 6. If blocked, call `ovld protocol ask --session-key <sessionKey> --ticket-id <ticket_id> --question "..."` and stop.
 7. Deliver last with `ovld protocol deliver --session-key <sessionKey> --ticket-id <ticket_id> --summary "..."`, including `changeRationales` for each meaningful behavioral file change.
@@ -113,5 +114,5 @@ For the `record-change-rationales` command and full payload shape with optional
 - [reference/context.md](reference/context.md) — Shared state, attachments, and large artifact policy
 - [reference/shell-escaping.md](reference/shell-escaping.md) — Heredoc stdin piping for special characters in summaries and payloads
 
-<!-- version: 0.5.8 -->
+<!-- version: 0.5.9 -->
 

package/plugins/claude/skills/overlord-ticket/reference/cli.md

@@ -14,6 +14,14 @@ In a git workspace, `attach` automatically creates a local git checkpoint for ea
 ovld protocol update --session-key <sessionKey> --ticket-id $TICKET_ID --summary "What you did and why." --phase execute
 ```
 
+## Heartbeat
+
+```bash
+ovld protocol heartbeat --session-key <sessionKey> --ticket-id $TICKET_ID --phase execute --percent 40 --note "Running the integration suite"
+```
+
+Use `heartbeat` for liveness pings and transient UI telemetry when you have no meaningful narrative summary to post. It updates the attached session without creating a ticket event.
+
 Supported `--phase` values:
 
 - `draft`
@@ -34,7 +42,7 @@ Event types:
 - `discussion_summary` for important discussion outcomes that should remain visible on the ticket
 - `decision` for explicit non-file decisions made during follow-up discussion
 
-Post-delivery follow-up modes:
+- Post-delivery follow-up modes:
 
 - User follow-up messages default to `discussion` intent while the ticket is in review.
 - Use `ovld protocol update --begin-follow-up-work --follow-up-intent execution --summary "Beginning follow-up work."` before moving a delivered/review ticket back to execution.

package/plugins/cursor/skills/overlord-ticket/SKILL.md

@@ -15,6 +15,7 @@ Use this mode when the prompt already contains a ticket ID or explicitly says th
 2. The attach response prints JSON to stdout containing `session.sessionKey`. The CLI also persists this key automatically so subsequent `ovld protocol` commands in the same working directory resolve it without `--session-key`. If auto-resolution fails, pass `--session-key <sessionKey>` explicitly on every subsequent call.
 3. Treat the Overlord ticket prompt as authoritative for the objective, constraints, and delivery target.
 4. Post updates while working: `ovld protocol update --session-key <sessionKey> --ticket-id <ticket_id> --summary "..." --phase execute`.
+   During long mechanical stretches with nothing meaningful to post, send `ovld protocol heartbeat --session-key <sessionKey> --ticket-id <ticket_id> [--phase execute] [--percent <0-100>] [--note "..."]` instead of an empty update.
 5. Follow-up messages after the initial ticket are captured automatically by the installed Cursor `beforeSubmitPrompt` hook (see `~/.cursor/hooks.json`) and stay in discussion intent while the ticket is in review. Do not post `user_follow_up` manually unless the hook is unavailable.
 6. If blocked, call `ovld protocol ask --session-key <sessionKey> --ticket-id <ticket_id> --question "..."` and stop.
 7. Deliver last with `ovld protocol deliver --session-key <sessionKey> --ticket-id <ticket_id> --summary "..."`, including `changeRationales` for each meaningful behavioral file change.
@@ -113,5 +114,5 @@ For the `record-change-rationales` command and full payload shape with optional
 - [reference/context.md](reference/context.md) — Shared state, attachments, and large artifact policy
 - [reference/shell-escaping.md](reference/shell-escaping.md) — Heredoc stdin piping for special characters in summaries and payloads
 
-<!-- version: 0.5.8 -->
+<!-- version: 0.5.9 -->
 

package/plugins/cursor/skills/overlord-ticket/reference/cli.md

@@ -14,6 +14,14 @@ In a git workspace, `attach` automatically creates a local git checkpoint for ea
 ovld protocol update --session-key <sessionKey> --ticket-id $TICKET_ID --summary "What you did and why." --phase execute
 ```
 
+## Heartbeat
+
+```bash
+ovld protocol heartbeat --session-key <sessionKey> --ticket-id $TICKET_ID --phase execute --percent 40 --note "Running the integration suite"
+```
+
+Use `heartbeat` for liveness pings and transient UI telemetry when you have no meaningful narrative summary to post. It updates the attached session without creating a ticket event.
+
 Supported `--phase` values:
 
 - `draft`
@@ -34,7 +42,7 @@ Event types:
 - `discussion_summary` for important discussion outcomes that should remain visible on the ticket
 - `decision` for explicit non-file decisions made during follow-up discussion
 
-Post-delivery follow-up modes:
+- Post-delivery follow-up modes:
 
 - User follow-up messages default to `discussion` intent while the ticket is in review.
 - Use `ovld protocol update --begin-follow-up-work --follow-up-intent execution --summary "Beginning follow-up work."` before moving a delivered/review ticket back to execution.

package/plugins/overlord/README.md

@@ -37,7 +37,7 @@ Tool names match the hosted Overlord MCP server (`supabase/functions/mcp/tools.t
 - Project resolution: `discover_project`
 - Ticket search: `search_tickets` — keyword search + status/filter (same filters as `ovld protocol search-tickets`)
 - Ticket session flow: `attach`, `connect`, `load_ticket_context` (CLI `load-context` only; not on hosted MCP), `prompt`
-- Progress and review flow: `update`, `record_change_rationales`, `ask`, `deliver`
+- Progress and review flow: `update`, `heartbeat`, `record_change_rationales`, `ask`, `deliver`
 - Shared context: `read_context`, `write_context`
 - Objective attachments: `list_attachments`, `prepare_attachment_upload`, `finalize_attachment_upload`, `get_attachment_download_url`, `upload_attachment_file`
 - Local runner queue: `request_execution`, `claim_execution`, `complete_execution_launch`, `fail_execution_launch`

package/plugins/overlord/scripts/overlord-mcp.mjs

@@ -373,6 +373,40 @@ const tools = [
     }),
     subcommand: 'update'
   },
+  {
+    name: 'heartbeat',
+    description:
+      'Send a lightweight Overlord liveness ping without posting a ticket event. Optional phase/percent/note telemetry is stored on the session row.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session_key: { type: 'string' },
+        ticket_id: {
+          type: 'string',
+          description: 'Ticket identifier (e.g. 1:899). Also accepts UUID.'
+        },
+        phase: {
+          type: 'string',
+          enum: ['draft', 'execute', 'review', 'deliver', 'complete', 'blocked', 'cancelled']
+        },
+        percent: { type: 'number' },
+        note: { type: 'string' },
+        external_url: { type: ['string', 'null'] },
+        external_session_id: { type: ['string', 'null'] }
+      },
+      required: ['session_key', 'ticket_id']
+    },
+    toCliFlags: args => ({
+      'session-key': args.session_key,
+      'ticket-id': args.ticket_id,
+      phase: args.phase,
+      percent: args.percent,
+      note: args.note,
+      'external-url': args.external_url,
+      'external-session-id': args.external_session_id
+    }),
+    subcommand: 'heartbeat'
+  },
   {
     name: 'record_change_rationales',
     description: 'Persist structured change rationale rows without posting a separate update.',

package/plugins/overlord/skills/overlord-ticket/SKILL.md

@@ -15,6 +15,7 @@ Use this mode when the prompt already contains a ticket ID or explicitly says th
 2. The attach response prints JSON to stdout containing `session.sessionKey`. The CLI also persists this key automatically so subsequent `ovld protocol` commands in the same working directory resolve it without `--session-key`. If auto-resolution fails, pass `--session-key <sessionKey>` explicitly on every subsequent call.
 3. Treat the Overlord ticket prompt as authoritative for the objective, constraints, and delivery target.
 4. Post updates while working: `ovld protocol update --session-key <sessionKey> --ticket-id <ticket_id> --summary "..." --phase execute`.
+   During long mechanical stretches with nothing meaningful to post, send `ovld protocol heartbeat --session-key <sessionKey> --ticket-id <ticket_id> [--phase execute] [--percent <0-100>] [--note "..."]` instead of an empty update.
 5. Follow-up messages after the initial ticket are captured automatically by the installed `UserPromptSubmit` hook and stay in discussion intent while the ticket is in review. Do not post `user_follow_up` manually unless the hook is unavailable.
 6. If blocked, call `ovld protocol ask --session-key <sessionKey> --ticket-id <ticket_id> --question "..."` and stop.
 7. Deliver last with `ovld protocol deliver --session-key <sessionKey> --ticket-id <ticket_id> --summary "..."`, including `changeRationales` for each meaningful behavioral file change.
@@ -114,5 +115,5 @@ For the `record-change-rationales` command and full payload shape with optional
 - [reference/context.md](reference/context.md) — Shared state, attachments, and large artifact policy
 - [reference/shell-escaping.md](reference/shell-escaping.md) — Heredoc stdin piping for special characters in summaries and payloads
 
-<!-- version: 0.5.8 -->
+<!-- version: 0.5.9 -->
 

package/plugins/overlord/skills/overlord-ticket/reference/cli.md

@@ -14,6 +14,14 @@ In a git workspace, `attach` automatically creates a local git checkpoint for ea
 ovld protocol update --session-key <sessionKey> --ticket-id $TICKET_ID --summary "What you did and why." --phase execute
 ```
 
+## Heartbeat
+
+```bash
+ovld protocol heartbeat --session-key <sessionKey> --ticket-id $TICKET_ID --phase execute --percent 40 --note "Running the integration suite"
+```
+
+Use `heartbeat` for liveness pings and transient UI telemetry when you have no meaningful narrative summary to post. It updates the attached session without creating a ticket event.
+
 Supported `--phase` values:
 
 - `draft`
@@ -34,7 +42,7 @@ Event types:
 - `discussion_summary` for important discussion outcomes that should remain visible on the ticket
 - `decision` for explicit non-file decisions made during follow-up discussion
 
-Post-delivery follow-up modes:
+- Post-delivery follow-up modes:
 
 - User follow-up messages default to `discussion` intent while the ticket is in review.
 - Use `ovld protocol update --begin-follow-up-work --follow-up-intent execution --summary "Beginning follow-up work."` before moving a delivered/review ticket back to execution.