@skrr-ai/cli 0.1.111 → 0.1.114

package/docs/v1/README.md

@@ -9,6 +9,7 @@ This edition was reviewed on **2026-10-10** against CLI **0.1.95**, daemon **0.8
 | Sign in and create your first Task | [Quickstart](quickstart.md) |
 | Make a read-only HTTP request with a scoped key | [Public API](api.md) |
 | Fix sign-in, errors, quotas, permissions, or a failed upgrade | [Operations and recovery](operations.md) |
+| Schedule, inspect, revise or cancel 1–10 lookbacks | [Lookback plans](lookback-plans.md) |
 | Understand what changed in this guide | [Changelog](changelog.md) |
 
 The workspace CLI uses the account/workspace `/api` surface. The Managed Agents public API uses `/v1` and Space-scoped API keys. A personal access token for CLI automation is a different credential. Choose the surface before issuing a credential.

package/docs/v1/lookback-plans.md

@@ -0,0 +1,88 @@
+# Scheduled lookback plans
+
+A plan provides 1–10 opportunities to inspect fresh evidence. Each check may stay silent. It does not promise one message per check.
+
+## Create
+
+Read a conversation belonging to the intended agent:
+
+```sh
+skrr convos messages YOUR_CONVERSATION_ID --json
+```
+
+Choose a completed assistant reply (`isCreatedByUser: false`, `unfinished: false`). Copy its actual `messageId` and completion `updatedAt`. The source is immutable: do not substitute the current clock or a user message.
+
+Generate a template without signing in, then replace all three source placeholders:
+
+```sh
+skrr followups plans example > plan.json
+```
+
+The generated file contains:
+
+```json
+{
+  "objective": "Check deployment health",
+  "stopCondition": "Deployment is ready or the owner cancels",
+  "source": {
+    "conversationId": "YOUR_CONVERSATION_ID",
+    "messageId": "YOUR_COMPLETED_ASSISTANT_MESSAGE_ID",
+    "replyCompletedAt": "ACTUAL_REPLY_COMPLETION_ISO_TIMESTAMP"
+  },
+  "steps": [
+    {
+      "id": "health-check",
+      "instruction": "Read the latest original conversation. Report readiness once; otherwise stay silent.",
+      "when": { "kind": "relative", "offset": "10m" }
+    }
+  ]
+}
+```
+
+```sh
+skrr followups plans create --agent YOUR_AGENT_ID --from-json plan.json --json
+```
+
+Relative time is measured from that reply's completion, so ensure the resulting time is still in the future. An envelope can explicitly separate delivery from evidence:
+
+```json
+{
+  "agentId": "YOUR_AGENT_ID",
+  "pinnedConversationId": "YOUR_CONVERSATION_ID",
+  "plan": { "objective": "...", "stopCondition": "...", "source": {}, "steps": [] }
+}
+```
+
+The envelope's abbreviated `plan` is structural guidance; replace it with the complete authored plan above. Optional delivery fields are `endpointId` and `endpointTarget`; source identity remains independent. `armed: true` confirms timer registration. A saved/pending result does not, and an existing terminal plan remains terminal on replay.
+
+## Time forms
+
+Each step's `when` accepts one of these shapes. Replace example dates with future dates:
+
+```json
+{"kind":"relative","offset":"10m"}
+```
+
+```json
+{"kind":"absolute","at":"2026-10-21T12:00:00Z"}
+```
+
+```json
+{"kind":"local","dateTime":"2026-10-21T09:00:00","timezone":"America/Los_Angeles"}
+```
+
+Absolute timestamps require `Z` or a UTC offset. Local times require an IANA timezone; ambiguous and nonexistent DST times are refused. A step may also have `label` and `expiresAfter` (for example `"1h"`). After expiry, the check must not execute. Top-level `title` and `timezone` are optional.
+
+## Inspect, revise and cancel
+
+```sh
+skrr followups plans list --agent YOUR_AGENT_ID --json
+skrr followups plans show PLAN_ID --json
+skrr followups plans revise PLAN_ID --revision 1 --from-json revised-plan.json --json
+skrr followups plans cancel PLAN_ID --revision 2 --reason "No longer needed" --json
+skrr followups plans observability --agent YOUR_AGENT_ID --json
+```
+
+Use the current revision returned by `show`. A stale edit returns `LOOKBACK_CONFLICT` with HTTP 409; reread before deciding whether to edit again. Revision JSON is the full authored plan itself, with the exact original source and existing step IDs. Start from `plan.json`, preserve IDs from `show`, and edit pending instructions/times. Do not resubmit the full `show` response: server fields such as `state`, `runAt`, `expiresAt`, outcomes and claims are not authoring input. Completed evaluations consume the same lifetime allowance after edits.
+
+Cancellation is idempotent and fences remaining work; it does not retract a message already delivered. `observability` reports a bounded sample, not lifetime totals. Normal account authority, budgets, runtime support and delivery policies still apply. No feature-flag enrollment or special two-person activation is needed.

package/oclif.manifest.json

@@ -7406,6 +7406,17 @@
           "multiple": false,
           "type": "option"
         },
+        "initial-always-on": {
+          "description": "Start autonomous work after creation (default: on). Use off for a passive agent; explicit chat still works. Relationship-loop seeding is configured separately.",
+          "name": "initial-always-on",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "on",
+            "off"
+          ],
+          "type": "option"
+        },
         "no-relationship-loops": {
           "description": "Single-purpose agent: skip the system-managed relationship portfolio (conversation continuity, relationship pulse, commitment incubator, open-loop closer). Self-reflection is still seeded.",
           "name": "no-relationship-loops",
@@ -23332,7 +23343,7 @@
       "aliases": [],
       "args": {
         "state": {
-          "description": "Whether personal stored balance may pay for skrr Code overage",
+          "description": "Whether personal stored balance may pay for Skrr Code overage",
           "name": "state",
           "options": [
             "enabled",
@@ -23341,7 +23352,7 @@
           "required": true
         }
       },
-      "description": "Enable or disable personal skrr Code overage after included allowance is exhausted",
+      "description": "Enable or disable personal Skrr Code overage after included allowance is exhausted",
       "examples": [
         "<%= config.bin %> balance overage enabled",
         "<%= config.bin %> balance overage disabled",
@@ -23409,7 +23420,7 @@
     "balance:plan": {
       "aliases": [],
       "args": {},
-      "description": "Show your skrr Code plan, renewal state, available tiers, and the matching lifecycle page",
+      "description": "Show your Skrr Code plan, renewal state, available tiers, and the matching lifecycle page",
       "examples": [
         "<%= config.bin %> balance plan",
         "<%= config.bin %> balance plan --json"
@@ -23709,7 +23720,7 @@
     "balance:usage:breakdown": {
       "aliases": [],
       "args": {},
-      "description": "Aggregate settled skrr Code usage by model, surface, agent and member",
+      "description": "Aggregate settled Skrr Code usage by model, surface, agent and member",
       "examples": [
         "<%= config.bin %> balance usage breakdown",
         "<%= config.bin %> balance usage breakdown --json",
@@ -23801,7 +23812,7 @@
     "balance:usage:events": {
       "aliases": [],
       "args": {},
-      "description": "List the skrr Code charges and run/session attribution behind aggregate allowance usage",
+      "description": "List the Skrr Code charges and run/session attribution behind aggregate allowance usage",
       "examples": [
         "<%= config.bin %> balance usage events",
         "<%= config.bin %> balance usage events --limit 20 --json",
@@ -26984,7 +26995,7 @@
       "pluginName": "@skrr-ai/cli",
       "pluginType": "core",
       "strict": false,
-      "summary": "Start the skrr Code interactive coding agent in this directory",
+      "summary": "Start the Skrr Code interactive coding agent in this directory",
       "enableJsonFlag": false,
       "isESM": false,
       "relativePath": [
@@ -26997,7 +27008,7 @@
     "code:acp": {
       "aliases": [],
       "args": {},
-      "description": "Run the skrr Code ACP server over stdio (used by the skrr daemon)",
+      "description": "Run the Skrr Code ACP server over stdio (used by the skrr daemon)",
       "examples": [
         "<%= config.bin %> code acp"
       ],
@@ -27021,7 +27032,7 @@
     "code:doctor": {
       "aliases": [],
       "args": {},
-      "description": "Diagnose the local skrr Code engine, config sources, and trust posture",
+      "description": "Diagnose the local Skrr Code engine, config sources, and trust posture",
       "examples": [
         "<%= config.bin %> code doctor",
         "<%= config.bin %> code doctor --json"
@@ -27183,7 +27194,7 @@
     "code:install": {
       "aliases": [],
       "args": {},
-      "description": "Install the local skrr Code signed release; use --daemon to install on another machine",
+      "description": "Install the local Skrr Code signed release; use --daemon to install on another machine",
       "examples": [
         "<%= config.bin %> code install",
         "<%= config.bin %> code install --daemon <daemon-id>",
@@ -27732,7 +27743,7 @@
           ]
         }
       },
-      "description": "Migrate an existing OpenCode configuration into skrr Code",
+      "description": "Migrate an existing OpenCode configuration into Skrr Code",
       "examples": [
         "<%= config.bin %> code migrate opencode",
         "<%= config.bin %> code migrate opencode --apply",
@@ -27749,7 +27760,7 @@
           "dependsOn": [
             "apply"
           ],
-          "description": "Replace existing skrr Code files, moving each aside to a timestamped .bak first",
+          "description": "Replace existing Skrr Code files, moving each aside to a timestamped .bak first",
           "name": "overwrite",
           "allowNo": false,
           "type": "boolean"
@@ -27787,7 +27798,7 @@
     "code:rollback": {
       "aliases": [],
       "args": {},
-      "description": "Restore the previous verified local skrr Code release",
+      "description": "Restore the previous verified local Skrr Code release",
       "flags": {
         "json": {
           "description": "Emit the result as JSON",
@@ -27815,7 +27826,7 @@
     "code:run": {
       "aliases": [],
       "args": {},
-      "description": "Run skrr Code headlessly on a single prompt",
+      "description": "Run Skrr Code headlessly on a single prompt",
       "examples": [
         "<%= config.bin %> code run \"add a regression test for the parser\"",
         "<%= config.bin %> code run --json \"summarize the diff\"",
@@ -27842,7 +27853,7 @@
     "code:skrr-agent": {
       "aliases": [],
       "args": {},
-      "description": "Show or set the skrr agent a managed skrr Code session is attributed to",
+      "description": "Show or set the skrr agent a managed Skrr Code session is attributed to",
       "examples": [
         "<%= config.bin %> code skrr-agent",
         "<%= config.bin %> code skrr-agent --set Engineer",
@@ -27920,7 +27931,7 @@
     "code:update": {
       "aliases": [],
       "args": {},
-      "description": "Check or update the local skrr Code signed release; use --daemon to update another machine",
+      "description": "Check or update the local Skrr Code signed release; use --daemon to update another machine",
       "examples": [
         "<%= config.bin %> code update",
         "<%= config.bin %> code update --check",
@@ -45552,7 +45563,7 @@
     "followups:plans:create": {
       "aliases": [],
       "args": {},
-      "description": "Schedule a bounded plan of 1–10 lookbacks, each free to stay silent",
+      "description": "Schedule a bounded plan of 1–10 lookbacks, each free to stay silent\n\nInput is authored Plan JSON with objective, stopCondition, source and 1–10 steps. Generate an editable JSON file:\n\nskrr followups plans example > plan.json\n\nReplace the three source placeholders with a real completed assistant reply belonging to this agent. `skrr convos messages <conversation-id> --json` reads its messageId and completion updatedAt. Never use the current clock as a replacement anchor.\n\nRelative time is measured from source.replyCompletedAt, not command invocation. Choose an offset whose resulting time is still in the future.\n\nEach when supports {\"kind\":\"relative\",\"offset\":\"10m\"}, {\"kind\":\"absolute\",\"at\":\"2026-10-21T12:00:00Z\"}, or {\"kind\":\"local\",\"dateTime\":\"2026-10-21T09:00:00\",\"timezone\":\"America/Los_Angeles\"}. Replace example dates with future dates. Absolute time requires Z or a UTC offset; ambiguous/nonexistent local DST times are refused.\n\nOptional fields: title, timezone; per step: id, label, expiresAfter (for example \"1h\"). Revision retains the exact source and existing step IDs. Do not submit the show response unchanged: remove lifecycle fields such as state, runAt and expiresAt.\n\nA check may remain silent. Only armed:true confirms timer registration; saved/pending is not armed. Full guide is shipped at docs/v1/lookback-plans.md in the installed CLI package.\n\nCreate also accepts {\"agentId\":\"...\",\"pinnedConversationId\":\"...\",\"plan\":{...}}. Source and delivery destination are separate; pin the original conversation to return there.",
       "examples": [
         "<%= config.bin %> followups plans create --from-json plan.json --agent agent_1 --json"
       ],
@@ -45631,6 +45642,67 @@
         "create.js"
       ]
     },
+    "followups:plans:example": {
+      "aliases": [],
+      "args": {},
+      "description": "Print an editable Plan JSON template without signing in\n\nReplace the source placeholders with a real completed assistant reply before creating a plan. This command schedules nothing.",
+      "examples": [
+        "<%= config.bin %> followups plans example > plan.json"
+      ],
+      "flags": {
+        "bare": {
+          "description": "Bare mode — ignore keychain/file credential sources. Token must come from env or --token.",
+          "name": "bare",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "token": {
+          "description": "Bearer token for this invocation (debugging/impersonation). Overrides env and stored creds.",
+          "name": "token",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "workspace": {
+          "description": "Workspace ID for workspace-scoped requests (also sets X-Workspace-Id).",
+          "name": "workspace",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "profile": {
+          "description": "Which stored session to use. Each profile keeps its own credential and deployment, so signing into one does not sign you out of another. Also OVERSKY_PROFILE. List them with `profiles list`.",
+          "name": "profile",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "raw": {
+          "description": "With --json, keep the Mongo storage fields (_id next to id, __v) that the CLI otherwise strips. Also OVERSKY_CLI_RAW=1.",
+          "name": "raw",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "followups:plans:example",
+      "pluginAlias": "@skrr-ai/cli",
+      "pluginName": "@skrr-ai/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "autonomousCredentialPolicy": "delegated",
+      "resolveSpaceFlag": true,
+      "isESM": false,
+      "relativePath": [
+        "dist",
+        "commands",
+        "followups",
+        "plans",
+        "example.js"
+      ]
+    },
     "followups:plans:list": {
       "aliases": [],
       "args": {},
@@ -45841,7 +45913,10 @@
           "required": true
         }
       },
-      "description": "Revise pending lookbacks using the original source and step IDs",
+      "description": "Revise pending lookbacks using the original source and step IDs\n\nInput is authored Plan JSON with objective, stopCondition, source and 1–10 steps. Generate an editable JSON file:\n\nskrr followups plans example > plan.json\n\nReplace the three source placeholders with a real completed assistant reply belonging to this agent. `skrr convos messages <conversation-id> --json` reads its messageId and completion updatedAt. Never use the current clock as a replacement anchor.\n\nRelative time is measured from source.replyCompletedAt, not command invocation. Choose an offset whose resulting time is still in the future.\n\nEach when supports {\"kind\":\"relative\",\"offset\":\"10m\"}, {\"kind\":\"absolute\",\"at\":\"2026-10-21T12:00:00Z\"}, or {\"kind\":\"local\",\"dateTime\":\"2026-10-21T09:00:00\",\"timezone\":\"America/Los_Angeles\"}. Replace example dates with future dates. Absolute time requires Z or a UTC offset; ambiguous/nonexistent local DST times are refused.\n\nOptional fields: title, timezone; per step: id, label, expiresAfter (for example \"1h\"). Revision retains the exact source and existing step IDs. Do not submit the show response unchanged: remove lifecycle fields such as state, runAt and expiresAt.\n\nA check may remain silent. Only armed:true confirms timer registration; saved/pending is not armed. Full guide is shipped at docs/v1/lookback-plans.md in the installed CLI package.\n\nRevise accepts the plan itself, not a create envelope. Use the current --revision from show; a stale revision returns LOOKBACK_CONFLICT (409).",
+      "examples": [
+        "<%= config.bin %> followups plans revise PLAN_ID --revision 1 --from-json revised-plan.json --json"
+      ],
       "flags": {
         "bare": {
           "description": "Bare mode — ignore keychain/file credential sources. Token must come from env or --token.",
@@ -45991,7 +46066,7 @@
     "followups:remind": {
       "aliases": [],
       "args": {},
-      "description": "Remind the owner at a time — the reminder follow-up",
+      "description": "Remind the owner at a time. By default, deliver the literal content through owner notifications without an agent turn. Use --active for agent-written delivery.",
       "examples": [
         "<%= config.bin %> followups remind --subject task:OSK-42 --content \"pick the deploy up\" --in 2h",
         "<%= config.bin %> followups remind --subject conversation:conv_9 --content \"ask how the move went\" --at 2026-09-20T09:00:00Z --active --agent agent_1",
@@ -46081,28 +46156,28 @@
           "type": "boolean"
         },
         "agent": {
-          "description": "Agent ID (default: bound session agent)",
+          "description": "Agent ID (default: bound session agent). Attribution only unless --active is set",
           "name": "agent",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "endpoint": {
-          "description": "Delivery endpoint id (EndpointRegistry)",
+          "description": "Active only: delivery endpoint id; requires --active",
           "name": "endpoint",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "endpoint-target": {
-          "description": "Channel target for channel endpoints",
+          "description": "Active only: channel target for a channel endpoint; requires --active",
           "name": "endpoint-target",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "pin": {
-          "description": "Conversation id the reminder was authored in",
+          "description": "Active only: deliver into this conversation; requires --active. Do not combine with --endpoint other than pinned",
           "name": "pin",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -46612,7 +46687,7 @@
           "type": "option"
         },
         "endpoint": {
-          "description": "Delivery endpoint id (EndpointRegistry)",
+          "description": "Delivery endpoint id (defaults to main). Use --pin to deliver into a specific conversation",
           "name": "endpoint",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -46626,7 +46701,7 @@
           "type": "option"
         },
         "pin": {
-          "description": "Conversation id the watch was authored in",
+          "description": "Deliver into this conversation. Do not combine with --endpoint other than pinned",
           "name": "pin",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -137151,5 +137226,5 @@
       ]
     }
   },
-  "version": "0.1.111"
+  "version": "0.1.114"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skrr-ai/cli",
-  "version": "0.1.111",
+  "version": "0.1.114",
   "description": "Command-line interface for skrr",
   "license": "ISC",
   "author": "skrr",
@@ -558,7 +558,10 @@
         "description": "Your Agent Manager (HR Agent): create it, or repair an incomplete one"
       },
       "followups": {
-        "description": "Schedule an agent to come back once — reminders, watches, check-ins, and deferred actions"
+        "description": "Schedule agent follow-ups and bounded lookback plans"
+      },
+      "followups:plans": {
+        "description": "Schedule and manage bounded plans of 1–10 lookbacks"
       },
       "enterprise": {
         "description": "Enterprise deployment configuration for a workspace (admin)"