@letta-ai/letta-code 0.30.4 → 0.30.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.30.4",
+  "version": "0.30.6",
   "description": "Letta Code is a CLI tool for interacting with stateful Letta agents from the terminal.",
   "type": "module",
   "packageManager": "bun@1.3.0",

package/scripts/check-test-mock-isolation.js

@@ -91,7 +91,11 @@ function moduleMatches(moduleSpecifier, suffixes) {
 }
 
 function isRelativeInternalModule(moduleSpecifier) {
-  return moduleSpecifier.startsWith("../") || moduleSpecifier.startsWith("./");
+  return (
+    moduleSpecifier.startsWith("../") ||
+    moduleSpecifier.startsWith("./") ||
+    moduleSpecifier.startsWith("@/")
+  );
 }
 
 function lineAndColumn(sourceText, index) {

package/scripts/isolated-unit-tests.json

@@ -1,10 +1,25 @@
 {
   "tests": [
+    {
+      "path": "src/channels/discord-reconcile.test.ts",
+      "timeoutMs": 15000,
+      "reason": "Mocks the backend client module in beforeAll; the mock leaks into later files in the same process."
+    },
     {
       "path": "src/channels/discord-registry.test.ts",
       "timeoutMs": 15000,
       "reason": "Uses a top-level Bun module mock for the backend client."
     },
+    {
+      "path": "src/channels/slack-registry.test.ts",
+      "timeoutMs": 15000,
+      "reason": "Uses a top-level Bun module mock for the backend client."
+    },
+    {
+      "path": "src/channels/telegram-registry.test.ts",
+      "timeoutMs": 15000,
+      "reason": "Uses a top-level Bun module mock for the backend client."
+    },
     {
       "path": "src/channels/discord-service.test.ts",
       "timeoutMs": 15000,
@@ -55,6 +70,17 @@
       "timeoutMs": 15000,
       "reason": "Mutates the settings singleton, keychain test overrides, HOME, and the secrets service name."
     },
+    {
+      "path": "src/cli/reflection-worktree-completion.test.ts",
+      "timeoutMs": 15000,
+      "env": { "LETTA_CODE_TELEM": "1" },
+      "reason": "Exercises reflection worktree cleanup telemetry with real Git processes and the shared telemetry singleton."
+    },
+    {
+      "path": "src/cli/helpers/reflection-launcher.test.ts",
+      "timeoutMs": 15000,
+      "reason": "Exercises reflection launch preflight with real Git processes and temporary local-backend environment overrides."
+    },
     {
       "path": "src/telemetry/flush-auth.test.ts",
       "timeoutMs": 15000,

package/scripts/source-file-size-baseline.json

@@ -5,7 +5,7 @@
   "src/backend/local/local-backend.ts": 1014,
   "src/backend/local/local-store.ts": 3594,
   "src/backend/pi-stream-adapter.test.ts": 1304,
-  "src/cli/app/AppCoordinator.tsx": 5203,
+  "src/cli/app/AppCoordinator.tsx": 5188,
   "src/cli/app/AppView.tsx": 1735,
   "src/cli/app/use-approval-flow.ts": 1163,
   "src/cli/app/use-configuration-handlers.ts": 1433,
@@ -22,9 +22,9 @@
   "src/cli/mods/local-mod-loader.test.ts": 1043,
   "src/cli/reflection-transcript.test.ts": 1084,
   "src/cli/subcommands/skills.ts": 1264,
-  "src/headless.ts": 5243,
+  "src/headless.ts": 5242,
   "src/hooks/integration.test.ts": 1147,
-  "src/index.ts": 2798,
+  "src/index.ts": 2773,
   "src/mods/learning-harness.ts": 2434,
   "src/mods/mod-engine.test.ts": 2153,
   "src/mods/mod-engine.ts": 1847,
@@ -46,6 +46,6 @@
   "src/websocket/listener/commands/memory.ts": 1114,
   "src/websocket/listener/file-commands.ts": 1053,
   "src/websocket/listener/lifecycle.ts": 1052,
-  "src/websocket/listener/protocol-inbound.ts": 2313,
+  "src/websocket/listener/protocol-inbound.ts": 2315,
   "src/websocket/listener/protocol-outbound.ts": 1085
 }

package/skills/managing-shared-memory/SKILL.md

@@ -5,123 +5,89 @@ description: Create and manage shared memory — git-tracked repositories hosted
 
 # Managing Shared Memory
 
-Shared memory is memory created independently of any single agent, designed to be dynamically attached to or detached from multiple agents. Each unit of shared memory is a **shared memory repository**: a git-tracked filesystem hosted on Letta Cloud, owned by your organization rather than by one agent, reachable from any environment (sandboxes, remote machines, sessions).
+Shared memory is memory created independently of any single agent, designed to be dynamically attached to or detached from multiple agents. Each unit of shared memory is a **shared memory repository**: a git repository hosted on Letta Cloud, owned by your organization rather than by one agent, reachable from any environment (sandboxes, remote machines, sessions).
 
-Like the rest of your external memory, shared memory lives outside your system prompt — it is not in-context. Unlike the rest of your external memory, it is not scoped to *you* specifically, so each attached repository has its own local projection root and its own remote git origin, separate from your MemFS.
+Shared memory works exactly like your MemFS: attached repositories are real git checkouts on disk, and you read, edit, commit, and push them with ordinary git. The only differences are that each repository has its own projection root (next to your memory directory, not inside it) and its own remote origin, and other agents may be writing to it too.
 
 Create a shared memory repository when:
 - You have context an agent should be able to access that doesn't belong in its own MemFS (input files, datasets, docs, working artifacts)
 - Multiple agents need to read or write the same context
 - You want a versioned file store that survives across environments and sessions
 
-Every file change is a git commit, so history is always available.
+## Working with Files (the normal path)
 
-## Accessing Attached Shared Memory
-
-When shared memory is attached to you and you're running in a cloud sandbox/environment, it is projected on disk next to your memory directory — each repository at its own projection root:
+Attached shared memory is mounted next to your memory directory, one git checkout per repository:
 
 ```bash
-ls "$MEMORY_DIR/../"           # attached shared memory appears here by name
-cat "$MEMORY_DIR/../<repo-name>/<path>"
+ls "$MEMORY_DIR/../"                      # attached repositories appear here by name
+cat "$MEMORY_DIR/../<repo-name>/<path>"   # read like any file
 ```
 
-If you don't see an expected repository on disk, fall back to the API (below) — it always works regardless of environment.
-
-## API Operations
-
-Shared memory repositories are the `repositories` resource in the Letta API. All operations go through the API using `$LETTA_API_KEY` via the Bash tool. Use `https://api.letta.com` (or `$LETTA_BASE_URL` if set — e.g. when running under Letta Desktop, which proxies auth). Responses are JSON.
+Edit files with your normal file tools, then commit and push with git — the mount's origin and credentials are already configured:
 
 ```bash
-BASE="${LETTA_BASE_URL:-https://api.letta.com}"
-AUTH="Authorization: Bearer $LETTA_API_KEY"
+cd "$MEMORY_DIR/../<repo-name>"
+git add <files>
+git commit -m "describe the change"
+git push
 ```
 
-### Repositories
-
-```bash
-# Create
-curl -sS -X POST "$BASE/v1/repositories" -H "$AUTH" -H "Content-Type: application/json" \
-  -d '{"name": "shared-inputs"}'
-# → {"id": "repo-...", "name": "shared-inputs", "created_at": ..., "updated_at": ...}
-
-# List (paginated)
-curl -sS "$BASE/v1/repositories?limit=50&offset=0" -H "$AUTH"
-# → {"repositories": [...], "has_next_page": false}
+Unlike MemFS, the harness does not auto-push shared memory after turns — a commit you don't push is not visible to other agents or environments. Always push after committing.
 
-# Get one
-curl -sS "$BASE/v1/repositories/{repository_id}" -H "$AUTH"
+To pick up other agents' changes:
 
-# Delete (soft-delete)
-curl -sS -X DELETE "$BASE/v1/repositories/{repository_id}" -H "$AUTH"
+```bash
+git -C "$MEMORY_DIR/../<repo-name>" pull --rebase
 ```
 
-### Files
+If a push is rejected (another agent pushed first), `git pull --rebase` then push again.
 
-Files are text content addressed by path. Every mutation returns a `commit_sha` and the file's `content_sha256`.
+History is ordinary git history:
 
 ```bash
-# List files (optional: path_prefix, depth, ref)
-curl -sS "$BASE/v1/repositories/{repository_id}/files?path_prefix=docs/&depth=2" -H "$AUTH"
-# → {"files": [{"path": "docs/a.md", "type": "file"}, ...], "ref": "<sha>"}
-
-# Create
-curl -sS -X POST "$BASE/v1/repositories/{repository_id}/files" -H "$AUTH" \
-  -H "Content-Type: application/json" \
-  -d '{"path": "docs/a.md", "content": "hello"}'
-
-# Read (optional: ref for a historical version)
-curl -sS "$BASE/v1/repositories/{repository_id}/files/content?path=docs/a.md" -H "$AUTH"
-# → {"path": "docs/a.md", "content": "hello", "content_sha256": "...", "ref": "..."}
-
-# Update content and/or rename. The optional precondition fails the write
-# if the file changed since you last read it (use when multiple agents write).
-curl -sS -X POST "$BASE/v1/repositories/{repository_id}/files/content" -H "$AUTH" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "path": "docs/a.md",
-    "content": "updated",
-    "new_path": "docs/b.md",
-    "precondition": {"type": "content_sha256", "content_sha256": "<sha from last read>"}
-  }'
-
-# Delete
-curl -sS -X DELETE "$BASE/v1/repositories/{repository_id}/files/content" -H "$AUTH" \
-  -H "Content-Type: application/json" -d '{"path": "docs/b.md"}'
-# → {"success": true, "commit_sha": "..."}
+git -C "$MEMORY_DIR/../<repo-name>" log --oneline -- <path>
 ```
 
-### Version History
+## Managing Repositories (create / attach / detach)
+
+Use the `letta shared-memory` subcommand. It uses your harness auth (works even when `LETTA_API_KEY` is not in the shell env) and inherits the agent id from `AGENT_ID`, so `--agent` is only needed when targeting another agent.
 
 ```bash
-# List commits (optionally scoped to one path)
-curl -sS "$BASE/v1/repositories/{repository_id}/versions?path=docs/a.md&limit=20" -H "$AUTH"
-# → {"commits": [{"sha": "...", "message": "...", "timestamp": "...", "author_name": ...}]}
+# List org repositories (marks which are attached to you)
+letta shared-memory list
 
-# Read a file as of a specific commit
-curl -sS "$BASE/v1/repositories/{repository_id}/versions/{sha}?path=docs/a.md" -H "$AUTH"
-```
+# Create a repository
+letta shared-memory create --name shared-notes
 
-### Attaching Shared Memory to Agents
+# Attach to yourself: attaches via the API, clones the local mount at
+# $MEMORY_DIR/../shared-notes, and recompiles the system prompt projection
+letta shared-memory attach shared-notes
 
-Attaching projects the repository into the agent's environments; detaching removes it. Neither changes the agent's own MemFS.
+# Attach to another agent (its mount materializes in that agent's environments)
+letta shared-memory attach shared-notes --agent agent-...
 
-```bash
-# List shared memory attached to an agent
-curl -sS "$BASE/v1/agents/{agent_id}/repositories" -H "$AUTH"
+# Detach (leaves the local mount directory in place)
+letta shared-memory detach shared-notes
 
-# Attach
-curl -sS -X POST "$BASE/v1/agents/{agent_id}/repositories" -H "$AUTH" \
-  -H "Content-Type: application/json" -d '{"repository_id": "repo-..."}'
+# Repair/refresh mounts: clone or pull every attached repository. Use this when
+# the system prompt references a repository that is missing on disk (e.g. after
+# it was attached from another surface while this session was running).
+letta shared-memory sync
 
-# Detach
-curl -sS -X DELETE "$BASE/v1/agents/{agent_id}/repositories/{repository_id}" -H "$AUTH"
+# Commit history via the API (works even without a local mount)
+letta shared-memory history shared-notes --path docs/plan.md
 ```
 
-Attaching is asynchronous — after a POST, poll the list endpoint until the repository appears before relying on it. You can attach shared memory to yourself (`$AGENT_ID`) or to another agent to share context with it.
+## Troubleshooting
+
+- **Prompt lists a repository but `$MEMORY_DIR/../<name>` is missing** — the repository was attached without materializing the mount. Run `letta shared-memory sync`.
+- **`sync` reports "mount path already exists and is not a git repository"** — a plain directory (usually created by hand before the mount existed) is occupying the mount path. Inspect it, salvage anything worth keeping, move or delete it, then re-run `letta shared-memory sync`.
+- **Never hand-clone the repository to another location (e.g. /tmp) to work around a broken mount** — fix the mount with `letta shared-memory sync` so every session and other agents see the same checkout.
+- **Permission denied under another agent's directory** — shared repositories mount per-agent. Only your own mount (under your agent directory) is accessible; another agent's mount of the same repository is walled off by the cross-agent guard. Run `letta shared-memory sync` to get your own mount.
+- **Push rejected (non-fast-forward)** — another agent pushed first: `git pull --rebase`, resolve any conflicts, push again.
 
 ## Notes and Limits
 
-- Shared memory files are **text** content; binary files are not supported via the files API.
-- Attached shared memory is not scoped to you — another agent may edit the same files at any time. Use the `content_sha256` precondition on updates when multiple agents may write the same file; on failure, re-read and retry.
 - Shared memory is not part of your system prompt. Writing to it does not change your in-context memory — for that, edit your memory blocks or MemFS files.
-- SDK equivalent: `@letta-ai/letta-agent-sdk` exposes these operations as `client.repositories` (with `files` and `versions` helpers) and supports attaching shared memory for a session's lifetime via `resources: [{ type: "repository", repositoryId }]` on cloud sessions.
+- Attaching is asynchronous on the server; `letta shared-memory attach` waits for the attachment to be visible before cloning.
+- SDK/API equivalent for programmatic callers: `@letta-ai/letta-agent-sdk` exposes these operations as `client.repositories` (with `files` and `versions` helpers), and shared memory can be attached for a session's lifetime via `resources: [{ type: "repository", repositoryId }]` on cloud sessions. The REST resource is `/v1/repositories`.

package/skills/scheduling-tasks/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: scheduling-tasks
-description: Schedules reminders and recurring tasks via the letta cron CLI. Use when the user asks to be reminded of something, wants periodic messages, or needs to manage scheduled tasks.
+description: Schedules reminders and recurring tasks via the letta cron CLI. Use when the user asks to be reminded of something, wants periodic work or check-ins, or needs to list, inspect, replace, or cancel scheduled tasks.
 ---
 
 # Scheduling Tasks
@@ -14,28 +14,24 @@ This skill lets you create, list, and manage scheduled tasks using the `letta cr
 - User wants a one-shot delayed message ("in 30 minutes, check on X")
 - User wants to see or cancel existing scheduled tasks
 
-## Where Schedules Run (`--runner`)
+## Where Schedules Run — Omit the Flags
 
-There are two schedule runners, selected with the optional `--runner local|cloud` flag:
+**Default guidance: omit `--runner` and `--computer`.** The CLI places the schedule so the work keeps running on the computer where it was created. Don't move scheduled work to a different computer than the active conversation without a reason: two computers working the same conversation can conflict.
 
-- **`cloud`** (default for cloud agents): a durable Cloud schedule stored by the Letta API. It fires from the cloud and executes in the agent's cloud sandbox, so it survives local shutdown — the computer, sandbox, or session that created it can disappear and the schedule still fires.
-- **`local`**: a task local to the current computer (`~/.letta/crons.json`), executed by the Letta session running there. It only fires while a session is running on that computer, and it dies with that computer's local state.
+Pass a flag only when you have a requirement the default can't infer:
 
-You normally don't need the flag — the default does the right thing. Local-backend agents (`agent-local-*`) and self-hosted servers always use the local runner.
+- **`--runner cloud`** — the schedule must fire no matter which computers are online; execute in the agent's cloud sandbox.
+- **`--computer <deviceId>`** — the work needs a specific connected computer (its filesystem, services, or credentials). Get the deviceId from `letta environments list`. If that computer is offline at fire time, execution falls back to the cloud sandbox.
+- **`--runner local`** — the work must only ever run on the current computer, even if that means missing fires while no session is running here.
 
-If the scheduled work must run on a **specific computer** (it needs that computer's filesystem, local services, or credentials — e.g. a bring-your-own machine like a Railway/VPS box or a home workstation), prefer a Cloud schedule that executes on that computer:
+The CLI reports its placement in the command output. If it warns that the schedule is local (this happens when the cloud scheduler cannot reach the current computer), the schedule only fires while a Letta session is running here — read the warning and decide whether that's acceptable.
 
-```bash
-letta cron add ... --computer <deviceId>
-```
-
-The deviceId comes from `letta environments list`. The computer must be connected to your Letta account (run `letta server` on it, or enable remote access in the desktop app). The schedule stays durable in the cloud; if the computer is offline when it fires, execution falls back to the agent's cloud sandbox. Use `--runner local` (run on the target computer itself) only when that sandbox fallback is unacceptable — a local task never runs anywhere but its own computer.
+### Fast Follow-ups vs Recurring Jobs
 
-Notes for the cloud runner:
+Two patterns cover most schedules:
 
-- Untargeted schedules execute in the agent's cloud sandbox, not on the computer where you created them; `--computer` executes on the named computer with sandbox fallback.
-- Recurring `--cron` expressions are currently interpreted in UTC (the CLI output includes a note about this). `--at` and `--every` are unaffected.
-- If creating a Cloud schedule fails, no schedule is created — there is no silent fallback to local storage. Retry, or pass `--runner local` deliberately.
+- **Fast follow-ups** ("check on the PR in 5m"): the default is right — same computer as the active conversation. If the session dies before it fires, the follow-up usually died with the task anyway.
+- **Recurring jobs** ("every Monday 11am, start the lunch order"): prefer durability. If the CLI warned that a recurring schedule is local, that's usually wrong for the user's intent — recreate it with `--runner cloud`, or `--computer` if the job needs a specific always-on computer. Also consider whether the job should post into a dedicated conversation rather than this one (continuity in one thread vs a fresh context per run).
 
 ## CLI Usage
 
@@ -59,7 +55,7 @@ letta cron add --name <short-name> --description <text> --prompt <text> <schedul
 
 | Flag | Type | Example |
 |------|------|---------|
-| `--every <interval>` | Recurring | `5m`, `2h`, `1d` |
+| `--every <interval>` | Recurring (cron shorthand) | `5m`, `2h`, `1d` |
 | `--at <time>` | One-shot | `"3:00pm"`, `"in 45m"` |
 | `--cron <expr>` | Raw cron (recurring) | `"0 9 * * 1-5"` |
 
@@ -69,8 +65,9 @@ letta cron add --name <short-name> --description <text> --prompt <text> <schedul
 |------|-------------|
 | `--agent <id>` | Agent ID (defaults to `LETTA_AGENT_ID` from the current shell/session) |
 | `--conversation <id>` | Conversation ID (defaults to `LETTA_CONVERSATION_ID` from the current shell/session, otherwise `"default"`) |
-| `--runner <runner>` | `cloud` or `local` — see "Where Schedules Run" above (defaults to `cloud` for cloud agents) |
-| `--computer <id>` | (cloud runner only) Execute on a connected computer instead of the agent's sandbox; falls back to the sandbox if the computer is offline |
+| `--runner <runner>` | `cloud` or `local` — normally omit; see "Where Schedules Run" above |
+| `--computer <id>` | Execute on a specific connected computer — normally omit |
+| `--once` | Mark `--at` as one-shot (already the default for `--at`) |
 
 ### Listing Tasks
 
@@ -78,14 +75,24 @@ letta cron add --name <short-name> --description <text> --prompt <text> <schedul
 letta cron list
 ```
 
-Optional filters: `--agent <id>`, `--conversation <id>`
+Optional filters: `--agent <id>`, `--conversation <id>`, `--runner local|cloud`
 
 ### Getting a Single Task
 
+`get` accepts an ID or name:
+
 ```bash
-letta cron get <task-id>
+letta cron get <id-or-name> [--runner local|cloud] [--agent <id>]
 ```
 
+### Reading Run History
+
+```bash
+letta cron runs --id <task-id> [--limit <n>] [--runner local|cloud] [--agent <id>]
+```
+
+For local run history, `--run-id <id>` selects one run. Cloud history ignores that flag.
+
 ### Binding a Task to the Right Conversation
 
 If exact routing matters, pass both `--agent` and `--conversation` explicitly.
@@ -110,58 +117,60 @@ Then verify the binding explicitly:
 letta cron list --agent "$AGENT_ID" --conversation "$CONVERSATION_ID"
 ```
 
-### Deleting Tasks
+### Deleting or Replacing Tasks
+
+`delete` accepts an ID or name; `remove` is an alias.
 
 ```bash
 # Delete a specific task
-letta cron delete <task-id>
+letta cron delete <id-or-name> [--runner local|cloud] [--agent <id>]
 
-# Delete all tasks for the current agent
-letta cron delete --all
+# Delete all tasks for one agent
+letta cron delete --all --agent "$AGENT_ID"
 ```
 
-## Examples
+In-place editing is not available. To change a schedule, create and verify the replacement before deleting the old one.
 
-### "Remind me every morning at 9am to walk the dog"
+## Timezones — Convert Before Writing `--cron`
 
-```bash
-letta cron add \
-  --name "dog-walk-reminder" \
-  --description "Daily morning reminder to walk the dog" \
-  --prompt "Hey! It's 9am — time to walk the dog." \
-  --every 1d
-```
+Cloud-schedule recurring expressions (both `--cron` and the expression `--every` compiles to) are interpreted in **UTC**. Users say times in their local timezone, so convert before writing the expression: a user in PDT asking for "9am daily" needs `--cron "0 16 * * *"` (9am PDT = 16:00 UTC; 17:00 during PST). State the conversion in your reply so the user can catch a wrong assumption. Local-runner tasks use the computer's local timezone — no conversion. `--at` stores one absolute timestamp parsed in the current process timezone, so it needs no conversion either.
 
-Note: `--every 1d` fires once daily at midnight. For a specific time like 9am, use a raw cron expression:
+## Examples
+
+### "Remind me every morning at 9am to walk the dog" (user in UTC−7)
 
 ```bash
 letta cron add \
   --name "dog-walk-reminder" \
-  --description "Daily 9am reminder to walk the dog" \
+  --description "Daily 9am (America/Los_Angeles) reminder to walk the dog" \
   --prompt "Hey! It's 9am — time to walk the dog." \
-  --cron "0 9 * * *"
+  --cron "0 16 * * *"
 ```
 
+Note: `--every 1d` fires daily at midnight (UTC on a Cloud schedule), so use `--cron` for a specific time of day, converting the user's local time to UTC first.
+
 ### "Check on the deploy in 30 minutes"
 
 ```bash
 letta cron add \
   --name "deploy-check" \
   --description "One-time check on deployment status" \
-  --prompt "The user asked you to check on the deploy — ask them how it went." \
+  --prompt "Check the deployment status and report the result here." \
   --at "in 30m"
 ```
 
-### "Every weekday at 5pm, remind me to submit my timesheet"
+### "Every weekday at 5pm, remind me to submit my timesheet" (user in UTC−7)
 
 ```bash
 letta cron add \
   --name "timesheet-reminder" \
-  --description "Weekday 5pm timesheet reminder" \
+  --description "Weekday 5pm (America/Los_Angeles) timesheet reminder" \
   --prompt "Friendly reminder: don't forget to submit your timesheet before EOD!" \
-  --cron "0 17 * * 1-5"
+  --cron "0 0 * * 2-6"
 ```
 
+Note the day shift: 5pm UTC−7 is midnight UTC the *next* day, so weekdays Mon–Fri become `2-6`. Always re-derive both the hour and the day fields after converting.
+
 ### "What reminders do I have?"
 
 ```bash
@@ -176,12 +185,8 @@ letta cron list --agent "$AGENT_ID" --conversation "$CONVERSATION_ID"
 
 ### "Cancel the dog walk reminder"
 
-First list to find the task ID, then delete:
-
 ```bash
-letta cron list
-# Find the task ID from the output, then:
-letta cron delete <task-id>
+letta cron delete dog-walk-reminder
 ```
 
 ## Writing Good Prompts
@@ -198,15 +203,14 @@ Include context about what the user originally asked for, so you can give a help
 - **Minimum granularity**: 1 minute. Intervals under 60 seconds are rounded up.
 - **Recurring tasks**: No longer auto-expire. They remain active until explicitly cancelled.
 - **One-shot cleanup (local runner)**: One-shot local tasks are garbage-collected 24 hours after firing.
-- **Timezone**: Local-runner tasks use the user's local timezone. Cloud-runner recurring `--cron` expressions are currently interpreted in UTC.
 - **Default binding precedence**: `letta cron add` uses `--agent` / `--conversation` first, then falls back to `LETTA_AGENT_ID` / `LETTA_CONVERSATION_ID`, then finally uses `"default"` for the conversation if no env var is present.
-- **Local scheduler requirement**: Local-runner tasks only fire while a Letta session is running on that computer (a WS listener must be active). If no session is running, tasks will be marked as missed. Cloud-runner schedules fire from the cloud regardless.
+- **Local scheduler requirement**: Local schedules only fire while a Letta session is running on their computer; fires while no session runs are marked as missed. Cloud schedules fire from the cloud regardless.
 - **`--at` for specific times**: `--at "3:00pm"` schedules a one-shot. If the time has already passed today, it schedules for tomorrow.
-- **`--every` for daily**: `--every 1d` fires daily at midnight. For a specific time of day, use `--cron` instead (e.g. `--cron "0 9 * * *"` for 9am daily).
+- **Cloud schedule creation failures are loud**: if creating a cloud schedule fails, no schedule is created — a failed create never silently becomes a local schedule. (The local placement for computers the cloud scheduler can't reach is decided before creation and reported in the output.)
 
 ## Cron Expression Reference
 
-For `--cron`, use standard 5-field cron syntax:
+For `--cron`, use numeric 5-field cron syntax (named days/months, seconds, `?`, `L`, and `#` are not supported):
 
 ```
 ┌───────────── minute (0-59)
@@ -218,9 +222,9 @@ For `--cron`, use standard 5-field cron syntax:
 * * * * *
 ```
 
-Common patterns:
+Common patterns (UTC on Cloud schedules):
 - `*/5 * * * *` — every 5 minutes
 - `0 */2 * * *` — every 2 hours
-- `0 9 * * *` — daily at 9am
-- `0 9 * * 1-5` — weekdays at 9am
-- `30 8 1 * *` — 8:30am on the 1st of each month
+- `0 9 * * *` — daily at 9:00 UTC
+- `0 9 * * 1-5` — weekdays at 9:00 UTC
+- `30 8 1 * *` — 8:30 UTC on the 1st of each month