@h-rig/contracts 0.0.6-alpha.103 → 0.0.6-alpha.119

package/dist/src/help-catalog.js

@@ -35,14 +35,15 @@ var TOP_LEVEL_SECTIONS = [
     subtitle: "every run is an isolated, collaborative OMP session on the selected target",
     commands: [
       {
-        command: "rig run start <task|#issue|--next>",
+        command: "rig run [start] <task|#issue|--next>",
         description: "Dispatch a run for a task (refuses if one is already active; --force overrides).",
         usecase: "Kick off work on a specific issue, or let Rig pick the next ready one.",
         examples: [
-          "rig run start 204            # by task/issue id",
-          "rig run start --next         # next ready task by deps/priority",
+          "rig run 204                  # by task/issue id",
+          "rig run --next               # next ready task by deps/priority",
+          "rig run --title 'Fix API' 204 # title override before the task ref",
           "rig run start 204 --force    # dispatch even if a run is already active",
-          "rig run start 204 --model opus-4.8   # override the agent model"
+          "rig run start 204 --model opus-4.8 --prompt 'focus tests'"
         ]
       },
       {
@@ -87,15 +88,27 @@ var TOP_LEVEL_SECTIONS = [
       },
       {
         command: "rig run stop <id> [--reason <text>]",
-        description: "Request a graceful stop of a run.",
+        description: "Request a graceful stop of a run (terminal).",
         usecase: "Halt a run that's off-track or no longer needed.",
         examples: ["rig run stop 019ee11f", "rig run stop 019ee11f --reason 'superseded by #210'"]
       },
       {
-        command: "rig run resume|restart <id>",
-        description: "Re-dispatch a task (detached runs start fresh).",
+        command: "rig run pause <id>",
+        description: "Park a live run (running \u2192 paused) without finalizing; the session stays attachable.",
+        usecase: "Hold an autonomous run mid-flight \u2014 free the agent without losing its place.",
+        examples: ["rig run pause 019ee11f"]
+      },
+      {
+        command: "rig run resume <id>",
+        description: "Resume a paused run (paused \u2192 running); the agent continues. A dead/stale run is re-dispatched fresh instead.",
+        usecase: "Un-pause a parked run, or retry a finished one.",
+        examples: ["rig run resume 019ee11f"]
+      },
+      {
+        command: "rig run restart <id>",
+        description: "Re-dispatch a task as a fresh run (new runId, clean runtime).",
         usecase: "Retry a failed/stopped run from a clean slate.",
-        examples: ["rig run restart 019ee11f", "rig run resume 019ee11f"]
+        examples: ["rig run restart 019ee11f"]
       },
       {
         command: "rig run timeline|replay <id>",
@@ -111,12 +124,12 @@ var TOP_LEVEL_SECTIONS = [
     subtitle: "github-issues / files task sources feed dispatch",
     commands: [
       {
-        command: "rig task list [--search <t>] [--status <s>]",
+        command: "rig task list [--search <t>] [--state <open|closed>]",
         description: "List tasks from the configured source, with filters.",
         usecase: "Find what's available to dispatch; filter by text or lifecycle status.",
         examples: [
           "rig task list",
-          "rig task list --status open",
+          "rig task list --state open",
           "rig task list --search 'auth'"
         ]
       },
@@ -128,10 +141,10 @@ var TOP_LEVEL_SECTIONS = [
         examples: ["rig task show 204", "rig task info 204"]
       },
       {
-        command: "rig task scope|deps|status <id>",
-        description: "Inspect a task's scope globs, dependencies, or lifecycle status.",
+        command: "rig task scope|deps --task <id>; rig task status",
+        description: "Inspect a task's scope globs/dependencies, or show project task status.",
         usecase: "Check what files a run may touch / what's blocking it.",
-        examples: ["rig task scope 204", "rig task deps 204", "rig task status 204"]
+        examples: ["rig task scope --task 204", "rig task deps --task 204", "rig task status"]
       },
       { command: "rig task lookup <term>", description: "Find a task by id/title substring.", examples: ["rig task lookup revoke-invite"] },
       { command: "rig task record \u2026", description: "Write task state/metadata back to the source.", usecase: "Programmatically update task lifecycle from scripts/CI." },
@@ -184,20 +197,19 @@ var TOP_LEVEL_SECTIONS = [
     title: "Placement & target \u2014 local vs remote execution",
     subtitle: "where runs execute; the backbone relay/registry is shared",
     commands: [
-      { command: "rig server status", description: "Show the selected placement (local/remote) and project-root link.", examples: ["rig server status"] },
+      { command: "rig server status", description: "Show the selected placement (local/remote) and task source.", examples: ["rig server status"] },
       { command: "rig server list", description: "List configured server targets.", examples: ["rig server list"] },
       {
-        command: "rig server use <alias>",
+        command: "rig server use <local|alias>",
         description: "Select a server target (execution placement).",
         usecase: "Switch a repo between local and a remote host for run execution.",
         examples: ["rig server use local", "rig server use prod-box"]
       },
       {
-        command: "rig server add|remove <alias>",
+        command: "rig server add --alias <alias> --host <host> [--port <n>] | remove <alias>",
         description: "Configure or remove a remote server target.",
-        examples: ["rig server add prod-box ubuntu@host", "rig server remove prod-box"]
+        examples: ["rig server add --alias prod-box --host ubuntu@host", "rig server remove prod-box"]
       },
-      { command: "rig server repair-link", description: "Repair the project-root link for the selected target.", usecase: "Fix a remote that shows unavailable after a host/checkout change.", examples: ["rig server repair-link"] },
       {
         command: "rig remote <list|add|test|status|\u2026>",
         description: "Lower-level remote endpoint management + run control over a remote.",
@@ -216,10 +228,10 @@ var TOP_LEVEL_SECTIONS = [
         examples: ["rig inbox approvals", "rig inbox inputs"]
       },
       {
-        command: "rig inbox approve <id> | respond <id> <text>",
-        description: "Approve an entry or answer a user-input prompt.",
-        usecase: "Unblock a paused run from the CLI.",
-        examples: ["rig inbox approve abc123", "rig inbox respond abc123 'use option B'"]
+        command: "rig inbox approve --run <id> --request <id> --decision approve|reject | respond --run <id> --request <id> --text <answer>",
+        description: "Attempt to resolve an approval or answer a user-input prompt; attach if one-shot delivery is unavailable.",
+        usecase: "Resolve pending requests from automation when the live run accepts out-of-band resolution.",
+        examples: ["rig inbox approve --run run1 --request abc123 --decision approve", "rig inbox respond --run run1 --request abc123 --text 'use option B'"]
       },
       { command: "rig inbox watch", description: "Stream inbox changes live.", examples: ["rig inbox watch"] },
       { command: "rig doctor", description: "Cheap health checks: session discovery, registry, selected target, workflow entries.", usecase: "First thing to run when something seems off.", examples: ["rig doctor"] }
@@ -230,14 +242,14 @@ var TOP_LEVEL_SECTIONS = [
     subtitle: "logs, artifacts, diffs, failure analysis",
     commands: [
       {
-        command: "rig inspect run-logs|logs --run <id>",
-        description: "Tail a run's process / session logs.",
+        command: "rig inspect run-logs --run <id> | logs --task <id>",
+        description: "Print run/session log lines.",
         usecase: "Debug why a run failed or stalled.",
-        examples: ["rig inspect run-logs --run 019ee11f", "rig inspect logs --run 019ee11f"]
+        examples: ["rig inspect run-logs --run 019ee11f", "rig inspect logs --task 204"]
       },
       { command: "rig inspect runs", description: "List runs from on-disk runtime state.", examples: ["rig inspect runs"] },
-      { command: "rig inspect artifact(s) --task <id>", description: "Inspect a task/run's artifacts.", examples: ["rig inspect artifacts --task 204"] },
-      { command: "rig inspect diff|graph", description: "Run diff / task dependency graph.", examples: ["rig inspect diff", "rig inspect graph"] },
+      { command: "rig inspect artifact --task <id> --file <name> | artifacts --task <id>", description: "Inspect a task/run's artifacts.", examples: ["rig inspect artifacts --task 204", "rig inspect artifact --task 204 --file task-result.json"] },
+      { command: "rig inspect diff --task <id> | graph [--task <id>]", description: "Run diff / task dependency graph.", examples: ["rig inspect diff --task 204", "rig inspect graph --task 204"] },
       { command: "rig inspect failures --task <id>", description: "Classified failure diagnostics for a task's runs.", usecase: "Triage repeated failures on one task.", examples: ["rig inspect failures --task 204"] },
       { command: "rig stats", description: "Aggregate run stats over a window.", examples: ["rig stats", "rig stats --since 7d"] }
     ]
@@ -278,15 +290,14 @@ var PRIMARY_GROUPS = [
   {
     name: "server",
     summary: "Compatibility server selector; the product Server target screen lives in Rig Cockpit.",
-    usage: ["rig server <status|list|add|use|repair-link|start> [options]"],
+    usage: ["rig server <status|list|add|use|remove> [options]"],
     commands: [
-      { command: "status", description: "Legacy automation-only: show the selected server and project-root link.", primary: true },
+      { command: "status", description: "Legacy automation-only: show the selected placement and task source.", primary: true },
       { command: "use local", description: "Legacy automation-only: switch this repo to local execution placement.", primary: true },
-      { command: "add <alias> <url>", description: "Legacy automation-only: save a remote server URL.", primary: true },
+      { command: "add --alias <alias> --host <host> [--port <n>]", description: "Legacy automation-only: save a remote execution target.", primary: true },
       { command: "use <alias>", description: "Legacy automation-only: select a remote execution target alias.", primary: true },
-      { command: "repair-link [--prepare|--backfill-only] [--repo owner/repo]", description: "Legacy automation-only: repair a server-host checkout link.", primary: true },
-      { command: "list", description: "Legacy automation-only: list saved local/remote server aliases.", primary: true },
-      { command: "start [--host <host>] [--port <n>]", description: "Legacy diagnostic-only: start a local rig-server process." }
+      { command: "remove <alias>", description: "Legacy automation-only: remove a saved remote execution target.", primary: true },
+      { command: "list", description: "Legacy automation-only: list saved local/remote server aliases.", primary: true }
     ],
     examples: [
       "rig server status        # legacy automation only",
@@ -302,9 +313,9 @@ var PRIMARY_GROUPS = [
       { command: "list [--assignee <login|me|@me>] [--state open|closed]", description: "Legacy automation-only: list tasks from the configured source.", primary: true },
       { command: "next [filters]", description: "Legacy automation-only: render the next matching task card.", primary: true },
       { command: "show <id>|--task <id> [--raw]", description: "Legacy automation-only: show a task payload for scripts.", primary: true },
-      { command: "run [#<issue>|<task-id>|--task <id>]", description: "Legacy/fenced: dispatch through the old task-run CLI path; not the task-detail dispatch path.", primary: true },
+      { command: "run [#<issue>|<task-id>|--task <id>] [--title <t>] [--model <m>] [--prompt <p>|--initial-prompt <p>]", description: "Legacy/fenced: dispatch through the CLI run path; not the task-detail dispatch path.", primary: true },
       { command: "ready", description: "Legacy automation-only: list task IDs that old dispatch can run now." },
-      { command: "validate|verify [--task <id>]", description: "Legacy automation-only: run configured task checks/review gates." },
+      { command: "validate|verify [--task <id>]", description: "Legacy automation-only: run configured task checks/review gates; failing checks exit nonzero." },
       { command: "details --task <id>", description: "Legacy automation-only: show full task info from the configured source." },
       { command: "reopen [--task <id> | --all] [--reason <text>]", description: "Legacy automation-only: reopen closed task(s) in the configured source." },
       { command: "artifacts|artifact-dir|artifact-write", description: "Legacy automation-only: inspect or write task artifacts." }
@@ -312,30 +323,30 @@ var PRIMARY_GROUPS = [
     examples: [
       "rig task list --assignee @me --limit 20   # legacy automation only",
       "rig task show 123 --raw                   # legacy automation only",
-      "rig task run #123 --runtime-adapter pi    # explicit legacy dispatch only"
+      "rig task run #123 --model opus-4.8 --prompt 'focus tests'"
     ],
     next: ["For normal UX, run bare `rig`, use Cockpit Server/Tasks, then dispatch from Task detail."]
   },
   {
     name: "run",
     summary: "Legacy automation-only run-record inspection; OMP Runs/collab is the live surface.",
-    usage: ["rig run <list|status|show|steer|stop|resume|restart> [options]"],
+    usage: ["rig run [start] <task|#issue|--next> [--title <t>] [--model <m>] [--prompt <p>|--initial-prompt <p>]", "rig run <list|status|show|steer|stop|resume|restart> [options]"],
     commands: [
+      { command: "[start] <task|#issue|--next> [--title <t>] [--model <m>] [--prompt <p>|--initial-prompt <p>]", description: "Legacy automation-only: dispatch a task run through the unified run launcher.", primary: true },
       { command: "list", description: "Legacy automation-only: list old run records from selected server/local state.", primary: true },
       { command: "status", description: "Legacy automation-only: render old active/recent run-record groups; not live OMP status.", primary: true },
       { command: "show <id>|--run <id> [--raw]", description: "Legacy automation-only: show an old run-record payload for scripts.", primary: true },
       { command: "attach <run-id>|--run <id>", description: "Legacy/fenced: not the Rig Cockpit attach path; use OMP Runs or `rig join <link>`.", primary: true },
       { command: "steer <run-id> --message <text>", description: "Legacy automation-only: queue steering into an old live worker.", primary: true },
-      { command: "stop [<run-id>|--run <id>]", description: "Legacy automation-only: request stop for old run records.", primary: true },
-      { command: "resume [<run-id>]", description: "Legacy automation-only: resume an interrupted old run record." },
-      { command: "restart [<run-id>]", description: "Legacy automation-only: re-dispatch an old run from a clean runtime." },
-      { command: "timeline --run <id> [--follow]", description: "Legacy automation-only: stream raw old timeline events." },
-      { command: "replay <run-id>|--run <id> [--with-session]", description: "Legacy automation-only: print an old consolidated run timeline." },
-      { command: "delete|cleanup", description: "Legacy automation-only: remove completed old run records/artifacts." }
+      { command: "stop <run-id>|--run <id> [--reason <text>]", description: "Legacy automation-only: request stop for old run records.", primary: true },
+      { command: "resume <run-id>|--run <id>", description: "Legacy automation-only: resume an interrupted old run record." },
+      { command: "restart <run-id>|--run <id>", description: "Legacy automation-only: re-dispatch an old run from a clean runtime." },
+      { command: "timeline|replay <run-id>|--run <id> [--with-session]", description: "Legacy automation-only: print an old consolidated run timeline." },
+      { command: "delete|cleanup [<run-id>|--run <id>]", description: "Legacy automation-only: remove stale live-registry entries; journals are retained." }
     ],
     examples: [
-      "rig run list          # legacy automation only",
-      "rig run show <run-id> # legacy automation only",
+      "rig run 204          # dispatch task 204",
+      "rig run --title 'Fix API' 204",
       "rig run stop <run-id> # legacy automation only"
     ],
     next: [
@@ -351,7 +362,7 @@ var PRIMARY_GROUPS = [
       { command: "approvals [--run <id>] [--task <id>]", description: "Legacy automation-only: list pending approval records.", primary: true },
       { command: "inputs [--run <id>] [--task <id>]", description: "Legacy automation-only: list pending user-input records.", primary: true },
       { command: "approve --run <id> --request <id> --decision approve|reject", description: "Legacy automation-only: resolve an approval record." },
-      { command: "respond --run <id> --request <id> --answer key=value", description: "Legacy automation-only: answer a user-input record." }
+      { command: "respond --run <id> --request <id> --text <answer> | --answer <answer>", description: "Legacy automation-only: answer a user-input record." }
     ],
     examples: [
       "rig inbox approvals # legacy automation only"
@@ -373,15 +384,17 @@ var PRIMARY_GROUPS = [
   {
     name: "inspect",
     summary: "Legacy automation-only artifact/log inspection; normal UX is OMP session history.",
-    usage: ["rig inspect <logs|artifacts|failures|graph|audit> --task <id>"],
+    usage: ["rig inspect <logs|artifact|artifacts|run-logs|runs|failures|graph|diff> [options]"],
     commands: [
       { command: "logs --task <id>", description: "Legacy automation-only: latest old run log for a task.", primary: true },
+      { command: "run-logs --run <id>", description: "Legacy automation-only: log lines for a specific run.", primary: true },
+      { command: "runs", description: "Legacy automation-only: list projected runs." },
+      { command: "artifact --task <id> --file <name>", description: "Legacy automation-only: preview one completion artifact." },
       { command: "artifacts --task <id>", description: "Legacy automation-only: list completion artifacts.", primary: true },
+      { command: "diff --task <id>", description: "Legacy automation-only: list task changed files." },
       { command: "failures --task <id>", description: "Legacy automation-only: recorded failures for a task.", primary: true },
-      { command: "graph", description: "Legacy automation-only: task dependency graph." },
-      { command: "audit", description: "Legacy automation-only: controlled-command audit trail." }
+      { command: "graph [--task <id>]", description: "Legacy automation-only: task dependency graph." }
     ],
-    examples: ["rig inspect logs --task <id> # legacy automation only"],
     next: ["For normal UX, use the OMP Runs screen and OMP session history."]
   },
   {

package/dist/src/index.d.ts

@@ -5,6 +5,9 @@ export * from "./graph";
 export * from "./runtime";
 export * from "./run-journal";
 export * from "./run-session-journal";
+export * from "./workflow-journal";
+export * from "./run-timeline";
+export * from "./run-record";
 export * from "./run-status";
 export * from "./conversation";
 export * from "./plugin";