portable-agent-layer 0.114.0 → 0.115.0-canary.2

package/README.md

@@ -95,6 +95,9 @@ pal cli status        # check your setup
 | `pal cli wrapped [--year <yyyy>]` | A year of your work in numbers, read from the event log |
 | `pal cli patterns` | How you work across projects, read from the event log |
 | `pal cli progress [show\|list\|open\|enter\|park\|wait\|done\|stopped\|decide\|attach\|follow-up]` | The progress tree: what you are on in this project, where it stopped, what is parked or waiting, and the decisions and artifacts on each node. Detours are child nodes and `done` returns to the parent. The active node rides along in every session and prompt, and your own commits attach to it at turn end |
+| `pal cli timebox [start\|status\|end]` | Stop work at a deadline: `start --for 15m` or `--until 18:00`. After the deadline every working tool call is refused except `pal cli` and edits to the report, so the agent stops and reports what it has |
+| `pal cli schedule [add\|list\|remove]` | Prompts added at a time of day, for you or for one project: `add --from 20:00 "suggest tasks that can run overnight"`. A due schedule is added to the next prompt you write inside its window, once a day by default (`--every-session`, `--every-prompt`), and nothing fires while no session is open |
+| `pal cli unattended [start\|log\|status\|done\|end]` | Work without you until a deadline: `start --until 05:30 --task … --fallback …`. Questions and subagents are refused, the agent cannot stop while approved tasks are left, and the rules, tasks and log come back after a compaction |
 | `pal cli content preserve` | Copy every Claude Code transcript, gzipped, into `memory/content/` before Claude Code deletes it (30 days by default). Runs on its own whenever a session closes; the content store never leaves the machine, so `export` skips it |
 | `pal cli events discord-nag <sent\|answered>` | For a bot outside PAL: record a nag it sent (`--kind <kind>`), or the answer to one and how long it took (`--after-sec <n>`), in the local event log |
 | `pal cli infer` | One model call for scripts and bots, on the active agent's route: prompt on stdin, reply on stdout. `--tier small\|medium\|large\|flagship` (on Claude: Haiku, Sonnet, Opus, Fable; on Codex: Luna, Sol, Sol at high effort, Astra; on Antigravity: Flash at low, medium and high effort, and no flagship; an agent without the tier asked refuses it), `--system <file>`, `--schema <file>` for a JSON reply checked against it, `--timeout <seconds>`. The call loads no PAL hooks or context; exits 1 with the reason when no route answers |
@@ -221,6 +224,7 @@ PAL ships with built-in skills that extend your agent's capabilities:
 | `reflect` | Diagnose why a PAL behavior didn't trigger |
 | `research-entity` | Research a company or person on the web: links, registry entry, recent news |
 | `rule-review` | Approve or deny the rules PAL drafted from your corrections |
+| `scheduled-prompts` | Set up a prompt that arrives at a time of day from now on, for you or one project |
 | `scientific-research` | Answer health and scientific questions from cited, verified sources: PubMed, guidelines, NEJM, Lancet, JAMA, BMJ |
 | `telos` | Inspect or update goals, beliefs, strategies, narratives |
 | `think` | Structured first-pass reasoning on a problem |

package/assets/skills/scheduled-prompts/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: scheduled-prompts
+license: MIT
+description: "Sets up a recurring prompt that PAL delivers at a time of day from now on — a suggestion, a reminder or a standing rule that applies after 20:00, every weekday at 9, or every evening. Extracts the window, weekdays, scope and repeat from the request, rewrites the text as an instruction to the assistant, reads it back for approval, then runs pal cli schedule add. Use when the user wants something to happen or be suggested at a time of day on an ongoing basis, or wants to list or remove such schedules."
+argument-hint: "<time or window> <what to prompt>"
+metadata:
+  source: portable-agent-layer
+  triggers:
+    - "scheduled-prompts"
+    - "scheduled prompts"
+    - "every day at"
+    - "from now on at"
+    - "schedule a prompt"
+    - "every evening"
+    - "every weekday at"
+    - "every morning"
+---
+
+# Scheduled prompts
+
+Turn $ARGUMENTS into a schedule that PAL adds to the conversation at a time of day from now on. Delivery is passive: a due schedule is attached as a system reminder to the first prompt the user writes inside its window. Nothing fires while no session is open, a missed window never fires late, and background notifications do not count as prompts. Schedules live in PAL's memory, never in the repository, and times are read in the user's configured timezone (`pal cli timezone`).
+
+## Workflow
+
+1. **Extract** from the request:
+   - **Window** — the local time it opens (`--from HH:MM`) and, when given, the time it closes (`--to HH:MM`; default midnight; it may pass midnight, so 22:00 to 02:00 belongs to the day it opened). A word like "morning" or "evening" without a clock time becomes a proposed time (08:00, 18:00), marked as assumed in the read-back.
+   - **Days** — weekdays only, as `--days mon-fri`, `sat,sun` or `mon,wed,fri`. Omit for every day.
+   - **Scope** — `--project <name>` when the request is about this project's work (the default is the current registered project, or the current folder when none is registered); `--user` when it is about the user generally, in every project.
+   - **Text** — the prompt rewritten as an instruction to the assistant, in the second person, under 500 characters. "After 20:00 suggest overnight tasks" becomes "Suggest one or two tasks that could run overnight with the unattended skill."
+2. **Pick the repeat** from the wording. An act-once request (suggest, remind, start, prepare, review) takes the default, daily: once per day per scope, so a user schedule fires once across all sessions and a project schedule once per project. A keep-in-mind rule (always, never, while, don't, keep) takes `--every-prompt`. Use `--every-session` only when the user asks for once per session.
+3. **Check for duplicates.** Run `pal cli schedule list` and compare the intent of each line with the new one; when one already says the same thing, tell the user and offer to keep it or replace it (`pal cli schedule remove <id>`, then add) rather than adding a second. Then read the opinions and rules always injected into context: when one already says the same thing at all hours, tell the user it can be retired through rule review once the schedule exists. Do not retire it yourself.
+4. **Read back** the schedule in one short block (window, days, scope, repeat, text). STOP and wait for explicit approval. Do not run `add` before it. Edits return to this step.
+5. **Add** after approval:
+   ```bash
+   pal cli schedule add "<text>" --from <HH:MM> [--to <HH:MM>] [--days <days>] [--project <name> | --user] [--every-session | --every-prompt]
+   ```
+   Show its output line verbatim and tell the user how to remove it: `pal cli schedule remove <id>`.
+
+To list schedules, run `pal cli schedule list` (`--here` for the current project only); each line carries id, scope, window, days, repeat, text and whether it is open or closed now. There is no edit command: a change is a remove followed by an add, read back as in step 4.
+
+## Output format
+
+- Before approval: one block with five labelled lines — **Window**, **Days**, **Scope**, **Repeat**, **Text** — followed by one approval question. Nothing runs before the answer.
+- After approval: the `add` command's output line as printed, the remove command, and one sentence on delivery: the prompt arrives as a system reminder on the first prompt written inside the window; nothing arrives while no session is open, and a missed window never fires late.
+- For a list request: the `pal cli schedule list` output, one line per schedule, unchanged.
+
+## When to use
+
+- The user asks for something to happen or be suggested at a time of day from now on: "after 20:00 suggest overnight tasks", "every weekday at 9 remind me to plan the day", "after 18:00 keep replies short", "every evening ask what to park".
+- The user asks what is scheduled, or wants a scheduled prompt changed or removed.
+
+## Do NOT use
+
+- A one-off reminder at a specific date, or work under a deadline: that is the `timebox` skill.
+- Work that should continue while the user is away: that is the `unattended` skill.
+- A recurring job that must run with no session open, such as a nightly build or a backup: use cron or the agent's own scheduler. A schedule only reaches a prompt the user writes.
+- A scheduled prompt has just arrived as a system reminder: act on it as the user's instruction. This skill creates schedules; it does not run them.

package/assets/skills/timebox/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: timebox
+license: MIT
+description: "Works on a task under a user-given time limit and stops at the deadline with a report of what was found or done so far. Use when the request names a duration or a clock time for the work (\"stop in 15 minutes\", \"spend at most an hour\", \"stop at 6 PM\", \"timebox this\")."
+argument-hint: <duration or HH:MM> <task>
+metadata:
+  source: portable-agent-layer
+  triggers:
+    - "timebox"
+    - "time box"
+    - "stop in"
+    - "spend at most"
+    - "stop at"
+    - "time limit"
+---
+
+# Timebox
+
+Work on $ARGUMENTS until the deadline the user set, then stop and report, wherever the work stands. PAL enforces the deadline for the current project or folder through its hooks; this skill is how to work inside it.
+
+## Workflow
+
+1. **Parse the limit** from the request. A duration ("15 minutes", "an hour and a half") becomes `--for 15m` or `--for 1h30m`; a clock time ("by 6 PM", "at 18:00") becomes `--until 18:00`, the next such local time. If no limit is clear, this is not the skill — do the task normally.
+2. **Start the box** before any other work:
+   ```bash
+   pal cli timebox start --for <15m|2h|1h30m> --task "<short task name>"
+   pal cli timebox start --until <HH:MM> --task "<short task name>"
+   ```
+   Add `--report <path>` only when the user asked for the result in a file. The command fails if a box is already running for this folder; then ask whether to replace it (`pal cli timebox end`, then start) or work inside the one that exists.
+3. **Work in small steps.** Run `pal cli timebox status` between steps; it prints the end time and the minutes left. Each user prompt during the box also carries "Time box until HH:MM, N min left". Plan the last step so it finishes before the deadline. Start nothing that cannot finish in the time left — a long build, a large download, a deep research pass — because a hook cannot interrupt a running command.
+4. **Stop at the deadline.** After it, PAL's PreToolUse hook refuses shell, edit and write, web search and fetch, subagent and question calls with a message starting "Time box ended at HH:MM … Stop working now". Only `pal cli …` commands (optionally piped into `head` or `tail`) and writes to the `--report` path still run. Read-only tools may still answer, but do not keep working with them. Do not work around a refusal; move straight to the report.
+5. **Report** in the final message, or in the report file when `--report` was given. Keep it short.
+6. **End the box**: `pal cli timebox end`. A user prompt sent after the deadline clears it automatically; run `end` anyway so the state is explicit.
+
+If the task finishes before the deadline, report then and run `pal cli timebox end` right away.
+
+## Output format
+
+The final message (or report file) has five parts, each one line or a short list:
+
+- **Done / found** — the concrete results so far.
+- **Not covered** — what the box cut off, or what was never reached.
+- **Next** — the first steps to take if the work resumes, with the box ended.
+- **Confidence** — a one-line judgment and its weakest point.
+- **Box** — `started HH:MM, ended HH:MM` and whether the task finished early or was cut at the deadline.
+
+## When to use
+
+- The user gives a duration or clock time for the work: "research this but stop in 15 minutes", "spend at most an hour on the refactor", "stop at 6 PM", "timebox this to 30 minutes".
+- The user says "timebox" or "time box" for any task.
+
+## Do NOT use
+
+- No time limit was given. Do the task normally; a time box without a user-stated limit is an invention.
+- The user is leaving and nobody will answer questions — that is the `unattended` skill, which sets its own deadline and handles the absence.
+- The user wants a reminder or an alarm with no work attached to it.

package/assets/skills/unattended/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: unattended
+license: MIT
+description: "Runs an approved list of tasks while the user is away — asleep, in a meeting, out for the afternoon — with nobody there to answer, then leaves a report for their return. Proposes finishable tasks and fallbacks, gets approval and a return time, starts the run with pal cli unattended, logs every decision, and finalises the report at the deadline. Use when the user says they are leaving and wants work to continue unattended, overnight, while they sleep, or until they are back."
+argument-hint: "[return time] [tasks or goal]"
+metadata:
+  source: portable-agent-layer
+  triggers:
+    - "unattended"
+    - "while I'm away"
+    - "work on this while I sleep"
+    - "overnight tasks"
+    - "night task"
+    - "until I'm back"
+    - "I'm going to bed"
+---
+
+# Unattended run
+
+Work through approved tasks with nobody present to answer, then hand back a report. Three phases: propose, run, report. Do not start the run until the user has approved the plan.
+
+## Phase A — Propose (before the user leaves)
+
+1. Resolve the current project from the working folder (`pal cli project resume <slug>` when the user names one). Read its notes, open progress nodes and recent sessions: tasks come only from this project.
+2. Draft candidate tasks. Keep a task only if it can be finished alone, with no decision that only the user can make. For each kept task write: what it produces, how it will be checked (tests or a build when the project has them, a visual comparison, sources cited, a reread against the brief), rough time, and resource cost (memory, network, paid APIs). Flag dropped tasks with the decision they need.
+3. Propose 1-2 fallback tasks the run takes when the approved list is finished early: deterministic, low-risk work such as fixing lint warnings, adding missing tests, or updating documentation.
+4. Ask, in one question with your agent's ask tool: the return time, where the report goes (a file path, a page the project serves, or an artifact), and extra rules. Suggest the rule categories: no paid or keyed APIs, no downloads, memory caps on heavy commands, files or services that are off-limits.
+5. Repeat back in short form: tasks in order, fallbacks, return time, report location, extra rules on top of the defaults listed below. STOP and wait for explicit approval. Edits to the list return to step 5.
+
+Default rules every run carries (`pal cli unattended start` stores them; `--rule` adds more):
+- Never ask. Decide, log the decision and its reason, list the question in the report.
+- Check notes and earlier sessions before listing a question.
+- Approved tasks, then fallbacks, nothing else. Other ideas become suggestions in the report.
+- Never delete, push, deploy or publish anything except the report.
+- One heavy process at a time. No subagents, no workflows.
+- Verify each step as if the user were present.
+- Only in a git repository: work on a branch, one logical step per commit, stage only your own changes, never push.
+
+## Phase B — Run (after approval)
+
+1. Set the deadline about 30 minutes before the return time so the report is final when the user is back. Start the run:
+   ```bash
+   pal cli unattended start --until <HH:MM> --task "<task 1>" --task "<task 2>" --fallback "<fallback>" --rule "<extra rule>" --report <path|url>
+   ```
+   Then `pal cli progress open "<run title>"` for the run's progress node.
+2. In a git repository, create the work branch. Take tasks in the approved order, one at a time.
+3. For each task: do it; verify it the way Phase A agreed (when the project has tests, run them twice and break-check every new test; when it has a build, run it); in a git repository, commit. Then `pal cli unattended log "<result> and how it was verified"` and `pal cli progress stopped "<next step>"`. Commits attach to the progress node on their own; do not attach them by hand.
+4. Log every non-obvious decision with its reason at the moment of deciding: `pal cli unattended log "<decision>: <reason>"`.
+5. Run `pal cli unattended status` between steps. Compare the minutes left with the estimated length of the next step; never start a step that cannot finish before the deadline, because a hook cannot interrupt a running command. Pick a shorter step or move to the report instead.
+6. Write the report to the agreed location as soon as the first task lands, with "(draft)" in its title. Update it after every task so a crash leaves a usable report behind.
+7. When the approved tasks are finished, take the fallbacks in order. The Stop hook refuses to end the turn before `pal cli unattended done`, so finishing early means moving on, not idling.
+8. Treat every refused tool call as a rule: questions to the user and subagent or workflow calls are refused during the run, and after the deadline every working tool is refused except `pal cli` and writes to the report path. The refusal depends on the agent's tool names being known to PAL, so never ask or delegate even when no hook stops you. Never work around a refusal; log it and continue with the next permitted step.
+9. After a context compaction, run `pal cli unattended status` and resume from the last logged step. Agents with a compaction hook also get the run's rules, tasks and log re-injected; re-read them first.
+
+## Phase C — Report (at the deadline)
+
+1. Finalise the report, removing "(draft)". Sections, in order:
+   - **Done** — each task, how it was verified, and its commits, test counts and build result where the project has them.
+   - **Comparisons** — for visual work, reference next to result, with an honest "falls short" note where it does.
+   - **Failed, skipped, reverted** — what, why, and what was reverted.
+   - **Questions for the user** — each answerable in one line; only questions the notes could not answer.
+   - **Unfinished work** — files left mid-change and what state they are in; in a git repository, the branch and its uncommitted files.
+   Label every inference of your own as such ("my reading:", "unverified:").
+2. If the report is served somewhere, open the served copy (the `playwright` skill, or fetch the URL) and confirm it matches the local file.
+3. `pal cli progress done`, then `pal cli unattended done`.
+4. When the user returns, reply first with a summary under 100 words: what landed, the report location, and the open questions. Then run `pal cli unattended end`.
+
+## Output format
+
+- Phase A ends with the short-form plan (tasks, fallbacks, return time, report location, extra rules) followed by one approval question. Nothing runs before the answer.
+- Phase B produces the task results (commits on the branch in a git repository), `pal cli unattended log` entries, progress-tree updates, and the draft report at the agreed location.
+- Phase C produces the final report with the five sections above and, on the user's return, a summary under 100 words naming the report location and the open questions.
+
+## When to use
+
+- The user is leaving (sleep, meeting, travel, the rest of the day) and wants work to continue with nobody there to answer.
+- The user asks for an overnight or night task, or wants the work to keep going while they are away or until they are back.
+- A list of self-contained tasks exists, or can be drawn from the current project, that needs no user decision mid-way.
+
+## Do NOT use
+
+- The user stays at the keyboard and only wants a time limit on the work: that is the `timebox` skill.
+- A single long-running command that should run in the background and be checked later.
+- Tasks that hinge on a decision only the user can make: propose them, flag the decision, and leave them out of the run.

package/assets/templates/settings.claude.json

@@ -112,7 +112,7 @@
     ],
     "PreToolUse": [
       {
-        "matcher": "Bash|Write|Edit",
+        "matcher": "Bash|Write|Edit|NotebookEdit|WebSearch|WebFetch|AskUserQuestion|Agent|Task|Workflow",
         "hooks": [
           {
             "type": "command",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.114.0",
+  "version": "0.115.0-canary.2",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {

package/src/cli/run-mode.ts

@@ -0,0 +1,214 @@
+/**
+ * pal cli timebox / pal cli unattended — start, inspect and end a run with a
+ * deadline for the current project or folder. The hooks enforce it.
+ */
+
+import { scopeOf } from "../hooks/lib/progress-tree";
+import {
+  clearRun,
+  deadlineFrom,
+  describeRun,
+  newRun,
+  type Run,
+  type RunKind,
+  readRun,
+  unattendedRules,
+  untilLabel,
+  writeRun,
+} from "../hooks/lib/run-mode";
+import { isInGitRepo } from "../hooks/lib/session-events";
+import { group, leaf, UsageError } from "../tools/lib/command";
+
+const FOR = {
+  type: "string",
+  value: "<duration>",
+  description: "How long, e.g. 15m, 2h or 1h30m",
+} as const;
+const UNTIL = {
+  type: "string",
+  value: "<HH:MM>",
+  description: "Local time it ends (the next one), or an ISO time",
+} as const;
+const REPORT = {
+  type: "string",
+  value: "<path|url>",
+  description:
+    "Where the report goes; edits to a local path still run after the deadline",
+} as const;
+
+function currentScope(): string {
+  return scopeOf(process.cwd());
+}
+
+function deadline(values: { for?: string; until?: string }): Date {
+  try {
+    return deadlineFrom(values);
+  } catch (err) {
+    throw new UsageError((err as Error).message);
+  }
+}
+
+function runOf(kind: RunKind): Run | null {
+  const run = readRun(currentScope());
+  return run?.kind === kind ? run : null;
+}
+
+function noRun(kind: RunKind): number {
+  console.error(`No ${kind} run in ${currentScope()}.`);
+  return 1;
+}
+
+function refuseIfRunning(): void {
+  const run = readRun(currentScope());
+  if (run)
+    throw new UsageError(
+      `A ${run.kind} run until ${untilLabel(run)} is already on here; end it first`
+    );
+}
+
+function printStatus(kind: RunKind): number {
+  const run = runOf(kind);
+  if (!run) return noRun(kind);
+  console.log(describeRun(run));
+  return 0;
+}
+
+function endRun(kind: RunKind): number {
+  const run = runOf(kind);
+  if (!run) return noRun(kind);
+  clearRun(run.scope);
+  console.log(`Ended the ${kind} run that was due at ${untilLabel(run)}.`);
+  return 0;
+}
+
+function startTimebox(values: {
+  for?: string;
+  until?: string;
+  task?: string;
+  report?: string;
+}): number {
+  refuseIfRunning();
+  const run = newRun({
+    kind: "timebox",
+    scope: currentScope(),
+    until: deadline(values),
+    task: values.task,
+    report: values.report,
+  });
+  writeRun(run);
+  console.log(
+    `Time box set: ends at ${untilLabel(run)}. After that only \`pal cli\` and report edits run.`
+  );
+  return 0;
+}
+
+function startUnattended(values: {
+  until?: string;
+  for?: string;
+  task?: string[];
+  fallback?: string[];
+  rule?: string[];
+  report?: string;
+}): number {
+  refuseIfRunning();
+  if (!values.task?.length) throw new UsageError("give each approved task with --task");
+  const run = newRun({
+    kind: "unattended",
+    scope: currentScope(),
+    until: deadline(values),
+    report: values.report,
+    tasks: values.task,
+    fallbacks: values.fallback ?? [],
+    rules: unattendedRules(isInGitRepo(process.cwd()), values.rule),
+  });
+  writeRun(run);
+  console.log(describeRun(run));
+  return 0;
+}
+
+function logEntry(text: string): number {
+  const run = runOf("unattended");
+  if (!run) return noRun("unattended");
+  writeRun({ ...run, log: [...run.log, { at: new Date().toISOString(), entry: text }] });
+  console.log(`Logged (${run.log.length + 1} entries).`);
+  return 0;
+}
+
+function markDone(): number {
+  const run = runOf("unattended");
+  if (!run) return noRun("unattended");
+  writeRun({ ...run, done: true });
+  console.log("Marked done: the agent may stop. The run ends when the user is back.");
+  return 0;
+}
+
+export const timeboxCommand = group({
+  summary: "Stop work at a deadline and report what was found",
+  commands: {
+    start: leaf({
+      summary: "Start a time box for the current project or folder",
+      options: {
+        for: FOR,
+        until: UNTIL,
+        task: { type: "string", value: "<text>", description: "What is being done" },
+        report: REPORT,
+      },
+      run: ({ values }) => startTimebox(values),
+    }),
+    status: leaf({
+      summary: "Show the time box and the time left",
+      run: () => printStatus("timebox"),
+    }),
+    end: leaf({ summary: "End the time box", run: () => endRun("timebox") }),
+  },
+});
+
+export const unattendedCommand = group({
+  summary: "Work without the user until a deadline: no questions, approved tasks only",
+  commands: {
+    start: leaf({
+      summary: "Start an unattended run with the approved tasks",
+      options: {
+        until: UNTIL,
+        for: FOR,
+        task: {
+          type: "string",
+          multiple: true,
+          value: "<text>",
+          description: "An approved task, in order (repeat)",
+        },
+        fallback: {
+          type: "string",
+          multiple: true,
+          value: "<text>",
+          description: "A pre-approved task for when the tasks run out (repeat)",
+        },
+        rule: {
+          type: "string",
+          multiple: true,
+          value: "<text>",
+          description: "A rule on top of the defaults (repeat)",
+        },
+        report: REPORT,
+      },
+      run: ({ values }) => startUnattended(values),
+    }),
+    log: leaf({
+      summary: "Append a timestamped entry to the run's log",
+      args: "<entry...>",
+      run: ({ positionals }) => logEntry(positionals.join(" ")),
+    }),
+    status: leaf({
+      summary: "Show the rules, tasks, log and time left",
+      run: () => printStatus("unattended"),
+    }),
+    done: leaf({
+      summary: "Every task and fallback is finished and the report is written",
+      run: markDone,
+    }),
+    end: leaf({
+      summary: "End the run (the user is back)",
+      run: () => endRun("unattended"),
+    }),
+  },
+});

package/src/cli/schedule.ts

@@ -0,0 +1,161 @@
+/**
+ * pal cli schedule — prompts the user wants added at a time of day, for
+ * themselves or for one project. The prompt hook injects the due ones.
+ */
+
+import { scopeOf } from "../hooks/lib/progress-tree";
+import { readAllProjects } from "../hooks/lib/projects";
+import {
+  addSchedule,
+  appliesHere,
+  newSchedule,
+  openWindowDay,
+  type Repeat,
+  readSchedules,
+  removeSchedule,
+  type Schedule,
+  scheduleLine,
+  USER_SCOPE,
+  windowLabel,
+} from "../hooks/lib/scheduled-prompts";
+import { group, leaf, UsageError } from "../tools/lib/command";
+
+interface AddValues {
+  from?: string;
+  to?: string;
+  days?: string;
+  project?: string;
+  user?: boolean;
+  "every-session"?: boolean;
+  "every-prompt"?: boolean;
+}
+
+function scopeFor(values: AddValues): string {
+  if (values.user && values.project)
+    throw new UsageError("give --user or --project, not both");
+  if (values.user) return USER_SCOPE;
+  return values.project === undefined
+    ? scopeOf(process.cwd())
+    : registeredProject(values.project);
+}
+
+function registeredProject(name: string): string {
+  if (readAllProjects().some((p) => p.name === name)) return name;
+  throw new UsageError(`no registered project "${name}"; see \`pal cli project list\``);
+}
+
+function repeatFor(values: AddValues): Repeat {
+  if (values["every-session"] && values["every-prompt"])
+    throw new UsageError("give --every-session or --every-prompt, not both");
+  if (values["every-prompt"]) return "every-prompt";
+  return values["every-session"] ? "every-session" : "daily";
+}
+
+function scopeLabel(schedule: Schedule): string {
+  return schedule.scope === USER_SCOPE ? "you, in every project" : schedule.scope;
+}
+
+function built(values: AddValues, text: string): Schedule {
+  if (!values.from) throw new UsageError("give the start time with --from <HH:MM>");
+  try {
+    return newSchedule({
+      scope: scopeFor(values),
+      from: values.from,
+      to: values.to,
+      days: values.days,
+      repeat: repeatFor(values),
+      text,
+    });
+  } catch (err) {
+    if (err instanceof UsageError) throw err;
+    throw new UsageError((err as Error).message);
+  }
+}
+
+function add(values: AddValues, text: string): number {
+  const schedule = built(values, text);
+  addSchedule(schedule);
+  console.log(
+    `Scheduled ${schedule.id} for ${scopeLabel(schedule)}: ${schedule.repeat}, ${windowLabel(schedule)}. Remove it with \`pal cli schedule remove ${schedule.id}\`.`
+  );
+  return 0;
+}
+
+function status(schedule: Schedule): string {
+  return openWindowDay(schedule) ? "open now" : "closed now";
+}
+
+function list(here: boolean): number {
+  const cwd = process.cwd();
+  const shown = readSchedules().filter((s) => !here || appliesHere(s, cwd));
+  if (!shown.length) {
+    console.log(here ? "No schedule applies here." : "No schedules.");
+    return 0;
+  }
+  for (const schedule of shown)
+    console.log(`${scheduleLine(schedule)}  [${status(schedule)}]`);
+  return 0;
+}
+
+function remove(id: string): number {
+  if (!removeSchedule(id)) {
+    console.error(`No schedule ${id}.`);
+    return 1;
+  }
+  console.log(`Removed ${id}.`);
+  return 0;
+}
+
+export const scheduleCommand = group({
+  summary: "Prompts added at a time of day, for you or for one project",
+  commands: {
+    add: leaf({
+      summary: "Schedule a prompt (once a day by default)",
+      args: "<text...>",
+      options: {
+        from: {
+          type: "string",
+          value: "<HH:MM>",
+          description: "Local time the window opens",
+        },
+        to: {
+          type: "string",
+          value: "<HH:MM>",
+          description: "Local time it closes (default midnight; may pass midnight)",
+        },
+        days: {
+          type: "string",
+          value: "<days>",
+          description: "Weekdays only, e.g. mon-fri or sat,sun",
+        },
+        project: {
+          type: "string",
+          value: "<name>",
+          description: "Only in this project (default: the current one)",
+        },
+        user: { type: "boolean", description: "For you, in every project" },
+        "every-session": {
+          type: "boolean",
+          description: "Once in each session inside the window",
+        },
+        "every-prompt": {
+          type: "boolean",
+          description: "On every prompt inside the window",
+        },
+      },
+      run: ({ values, positionals }) => add(values, positionals.join(" ")),
+    }),
+    list: leaf({
+      summary: "List the schedules and whether their window is open",
+      options: {
+        here: { type: "boolean", description: "Only those that apply in this folder" },
+      },
+      run: ({ values }) => list(values.here === true),
+    }),
+    remove: leaf({
+      summary: "Remove a schedule",
+      args: "<id>",
+      run: ({ positionals }) => remove(positionals[0]),
+    }),
+  },
+});

package/src/cli/tree.ts

@@ -27,6 +27,8 @@ import { patternsCommand } from "./patterns";
 import { telosCommand, timezoneCommand } from "./personal-context";
 import { progressCommand } from "./progress";
 import { ruleCommand } from "./rule";
+import { timeboxCommand, unattendedCommand } from "./run-mode";
+import { scheduleCommand } from "./schedule";
 import { serverCommand } from "./server";
 import { skillCommand } from "./skill";
 import { subagentCommand } from "./subagent";
@@ -187,6 +189,9 @@ export function cliTree(admin: AdminHandlers): Group {
       rule: ruleCommand,
       correction: correctionCommand,
       progress: progressCommand,
+      timebox: timeboxCommand,
+      unattended: unattendedCommand,
+      schedule: scheduleCommand,
       server: serverCommand,
       skill: skillCommand,
       subagent: subagentCommand,