@hienlh/ppm 0.23.24 → 0.23.25

package/docs/architecture/schedules.md

@@ -0,0 +1,90 @@
+# Schedules (prompt and script)
+
+> Part of the [PPM system architecture](../system-architecture.md). Gotchas live in
+> `src/services/schedule-script/CLAUDE.md`.
+
+A schedule is one row in `schedules`, of one of two kinds:
+
+- **prompt** — the original kind: on a 5-field cron, send a prompt to an AI chat in a project.
+- **script** — JavaScript that PPM runs in a child process, in one of two modes:
+  - **tick**: a fresh process on every fire of a 6-field cron (seconds first), at least 5 s apart
+    (`SCRIPT_MIN_INTERVAL_MS`). It ends when its `main` returns or at the schedule's timeout.
+  - **always-on**: one long-lived process that PPM starts, restarts after a crash with backoff
+    (5 s doubling to 5 min, reset after 10 min of uptime) and stops when the schedule is turned
+    off or deleted.
+
+A script is an ES module whose default export takes `ctx`:
+
+```js
+export default async function main(ctx) {
+  const last = ctx.state.last ?? 0;
+  ctx.log(`seen ${last}`);
+  ctx.state = { last: Date.now() };          // kept after a tick ends, or now with ctx.save()
+}
+```
+
+## The child process
+
+```
+scheduler (tick fire / always-on supervisor)
+  └─ script-launch.ts ── ScriptProcess ──spawn──> <ppm binary> --eval HARNESS_SOURCE   (BUN_BE_BUN=1)
+        ▲   IPC: call / result / hb / done            │  imports <PPM dir>/schedule-runs/<db>/<id>/script-<hash>.mjs
+        └── ctx-host.ts answers save, notify, ai.*    └─ watchdog Worker: dies with the server
+```
+
+- One child per schedule, never two: `instance-guard.ts` records the pid and a token, and on boot
+  `reconcileLeftovers` kills a leftover only after proving it is PPM's.
+- The child dies with the server however the server dies: stdin EOF, plus a Worker that checks
+  the parent every 250 ms for a script that blocks its event loop.
+- `stop()` aborts `ctx.signal`, then SIGKILLs after 5 s. A tick past its timeout is stopped the
+  same way and recorded as failed.
+- The environment is the server's minus `NOTIFY_SOCKET`; the cwd is the project folder.
+
+## `ctx`
+
+| Member | What it does |
+|---|---|
+| `inputs` | The schedule's input values (frozen); a secret input arrives decrypted. |
+| `state` / `save()` | One JSON value per schedule, at most 2 MB. A tick's state is kept when it ends, failed or not; always-on keeps it only through `save()`. |
+| `log(...)` / `console.*` | Lines into the schedule's log: secrets masked first, cut at 4096 chars, a 1000-line ring for the UI plus the run row. A line that still has no newline after 64 K chars is passed on cut there and the rest of it dropped, so a script printing without one cannot fill the server's memory. |
+| `notify({ title, body, sessionId? })` | PPM's notification fan-out (push, Telegram, ntfy). |
+| `ai.ask(prompt, { model, effort, system, jsonSchema, timeoutMs })` | One stateless model call on PPM's accounts: no tools, no `CLAUDE.md`, no session left behind. Default model `haiku`, 2 min. Answers `{ ok, text, json?, error?, timedOut?, costUsd }` instead of throwing. |
+| `ai.chat(key, prompt, { title, sessionId, timeoutMs, wait })` | A turn in a real PPM chat, one chat per `key` (or the given `sessionId`), shown live like any chat. Answers `{ ok, text, sessionId, busy?, error? }`; `busy` when someone else is mid-turn there. |
+| `ai.finished()` | The results of `ai.chat` turns started with `wait: false` that have ended since the last call, each returned once. They are kept in `schedule_ai_turns`, so a later tick can collect a turn an earlier one started. |
+| `signal` / `sleep(ms)` | Aborted when PPM stops the script; `sleep` rejects on abort. |
+
+`ai.chat` goes through the chat WebSocket handler over a loopback socket (`chat-loopback.ts`,
+`origin = "scheduler"`), so the turn sets the session's phase, rotates accounts and appears in
+the chat list. A new chat with no transcript is deleted, and its key forgotten.
+
+## Inputs and secrets
+
+A script declares inputs (`text`, `number`, `boolean`, `secret`; label, default, `required`).
+Values live in `input_values_json`; secret values are encrypted in `secrets_enc` and never leave
+the server: every `/api/schedules` answer goes through `toScheduleView`, which drops
+`secrets_enc` and `state_json`. A schedule with a required input left empty does not start.
+
+## Templates
+
+A template is a `<name>.ppm-schedule.json` file (`src/shared/schedule-template.ts`, format 1):
+the definition, the inputs with their defaults, and the script. It never carries a secret's
+value, ids, a session, state or a path of this machine.
+
+- **Export** (`GET /api/schedules/:id/export`, `ppm schedule export <id>`) writes that file.
+- **Import** (`POST /api/schedules/import`, `ppm schedule import <file> --project <name>`) parses
+  strictly (an unknown field or format is refused), shows the whole script, and requires the
+  user to state "I trust this code". The schedule is created **off**.
+
+Example templates ship in `templates/schedules/` and are tested as PPM runs them.
+
+## Surfaces
+
+- REST: `src/server/routes/schedules.ts` (CRUD, `run-now`, `runs`) and `schedules-script.ts`
+  (`logs`, `state`, `export`, `import`).
+- CLI: `ppm schedule add|list|rm|enable|disable|run-now|runs|export|import|state|set-state`.
+  Changes to a script schedule go through the running server, which owns the process.
+- UI: Settings → Schedules (`src/web/components/settings/schedules/`): the form with its script
+  editor and input declarations, the import sheet, the live log, and a status chip per row.
+- DB: migration 58 adds `kind`, `mode`, `description`, `script`, `inputs_json`,
+  `input_values_json`, `secrets_enc`, `state_json` to `schedules`, plus `schedule_runtime`
+  (one process per schedule), `schedule_chats` (key → chat) and `schedule_ai_turns`.

package/docs/architecture/workspace-and-ui.md

@@ -337,8 +337,10 @@ A **Design tab** puts a design chat beside a live, sandboxed canvas of what the
 - *Refresh is polling, not SSE*: the Cloudflare tunnel does not pass a client's disconnect through to PPM, so a held connection would leak. The page polls every 10 s while visible, at once after its own write and on becoming visible, backing off to 60 s on failure. An unchanged poll is a 304 from an ETag built from a per-design revision counter, the comment file's `stat` and the pinned snapshot, without reading `comments.json`.
 - *Re-pins and revokes reach an open page.* `/info` and every thread list carry `versionId`, the pinned snapshot. A list naming another one shows "This design was updated" with Reload; a new comment names the version it was made on and is refused (409 `version-changed`) when the link now shows another. Every reviewer write checks the link again once it holds the design lock (`assertGuestLinkOpen`), so one queued behind a snapshot is refused, and notifies nobody, if the link was revoked, expired, re-coded or paused meanwhile.
 - *Sign-in off pauses sharing.* With PPM sign-in off no code opens anything and no link can be created; the dialog says "Turn on PPM sign-in first" with a link to Settings → General and lists the links as "Paused: sign-in is off". They open again once sign-in is back on.
-- *The address* (`design-share-address.ts`) is the named tunnel's stable host when on, else the quick tunnel's, with a warning that it changes; under a supervisor it is read from `status.json` directly, because `tunnelService.getTunnelUrl()` keeps a URL that is gone. With no public address, Copy gives `location.origin`, which opens only where this PPM is reachable.
-- *Rate limits* (`design-share-rate-limit.ts`) are separate budgets, so polls cannot starve asset loads: files 1200 a minute and page/info/comment reads 120 a minute per client; writes 500 ms apart and 20 a minute per reviewer; 30 writes a minute per link, whoever sends them. The client is the peer address, and `CF-Connecting-IP` is believed only from a loopback peer whose `Host` is the tunnel's hostname (`design-share-client-key.ts`). Behind the supervisor every LAN and Tailscale reviewer arrives from loopback and shares one bucket; the budgets are sized for about ten such reviewers. A LAN client can forge both headers and choose its key, which buys nothing against the per-link cap.
+- *The address* (`design-share-address.ts`; cached 5 s for reviewer requests, read fresh for the owner's dialog) is the review address below whenever that is switched on, connected or not: falling back to PPM's own tunnel would hand reviewers an address that reaches all of PPM, so while it reconnects a stable hostname is kept with a warning and a quick one has none, and when no supervisor will ever act on the switch (none, or one from before `reshare`) the warning says to restart instead. Otherwise it is the named tunnel's stable host when on, else the quick tunnel's, with a warning that it changes; under a supervisor it is read from `status.json` directly, because `tunnelService.getTunnelUrl()` keeps a URL that is gone. The dialog says when the address opens PPM itself. With no public address, Copy gives `location.origin`, which opens only where this PPM is reachable.
+- *The dialog's Review-only address card* (`review-address-card.tsx`) switches the review address on and off and sets a domain up in place, so the option is found where links are made — including when PPM's own public link already gives them an address. It is Settings → Remote Access → Review links in small: the same status polling (`use-share-host-status.ts`) and the same Cloudflare sign-in and hostname steps (`review-address-setup.tsx`), with "which tunnel" asked only when PPM's own link is on a domain. Turning it on goes through the address block's start, so the block shows it coming up.
+- *The review address* (`src/services/share-host/`) lets links open while PPM itself stays private. A separate process the supervisor runs (`ppm __share_host__`, `share-host-worker.ts`) listens on loopback and forwards only `/s`, `/s/*` and `/assets/share-*` to the server, answering everything else itself with a 404 (`share-host-gateway.ts`), so no editor, `/api`, sign-in or WebSocket answers there whatever token is sent. It drops `Authorization` and `Cookie`, keeps `Host` and `CF-Connecting-IP`, caps bodies at 64 KB, and exits once its supervisor is gone. A connector of its own publishes it (`share-host-connector.ts`, `cloudflared-share.log`): a temporary trycloudflare address, the user's domain on a tunnel of its own (`ppm-share-<host>`), or the user's domain as a second hostname on PPM's named tunnel. In that last mode exactly one connector uses the tunnel, because Cloudflare spreads a hostname's requests over every connector of a tunnel: PPM's own while its public link is on (share hostname → worker, PPM's hostname → PPM, then 404), the share host's while it is off (share hostname → worker, then 404). Once a review hostname has been set up, PPM's named connector routes by hostname even when it carries no review route (switched off, worker down, moved to another tunnel): that DNS record still points at PPM's tunnel, and `--url` would answer it with PPM. The choice is the `share_host` config row (its run token a secret key), set up in Settings → Remote Access → Review links through `/api/share-host/*` (`share-host-setup.service.ts`, sign-in required); the server tells the supervisor with `reshare`, and a supervisor that predates it is reported as needing `ppm restart`. Run state is in `status.json` (`shareHostPid`, `shareHostPort`, `shareHostUrl`, `shareHostTunnelPid`, `shareHostWarning`).
+- *Rate limits* (`design-share-rate-limit.ts`) are separate budgets, so polls cannot starve asset loads: files 1200 a minute and page/info/comment reads 120 a minute per client; writes 500 ms apart and 20 a minute per reviewer; 30 writes a minute per link, whoever sends them. The client is the peer address, and `CF-Connecting-IP` is believed only from a loopback peer whose `Host` is a hostname a connector on this machine forwards — PPM's tunnel's or the review address's (`design-share-client-key.ts`). Behind the supervisor every LAN and Tailscale reviewer arrives from loopback and shares one bucket; the budgets are sized for about ten such reviewers. A LAN client can forge both headers and choose its key, which buys nothing against the per-link cap.
 - *Reviewer text and the AI.* A reviewer thread reaches the design chat only through the owner's Send to AI, with tags neutralised, fences neutralised, inside a `text` fence under a reviewer-specific untrusted header (`design-comments-prompt.ts`, `src/shared/untrusted-text.ts`); names and link labels are reduced to one quoted line. Nothing else a reviewer chose is printed: no selector for a reviewer's root, and its tag only when the server matched it in the source; any selector at all must have the exact shape the bridge's `cssPathOf` builds (`CSS_PATH_RE`). Residual risk, accepted: the model still reads the text, and in a design session file reads and writes are approved across the project, so a persuasive comment could talk the agent into copying project files into the design, which a later Update to latest would publish. What limits it is the header, the `.design/` ban in the instructions, the owner reading the whole message and sending it themselves, and the changed-files list before a re-pin. Also accepted: a design's own HTML can override the referrer policy toward the CDNs the design CSP allows and so leak the code; that HTML is the owner's.
 - *Notifications.* A reviewer's new comment or reply (not an edit or delete) raises the `design_review` event, "Reviewer comments" in Settings → Notifications, coalesced per link and sent at most once a minute (`design-share-notifier.ts`); its click opens the design, never a `/s/` tab.
 - e2e: `PPM_PLAYWRIGHT_MODULE=<playwright>/index.mjs node tests/e2e/design-share-e2e.mjs` (owner on a desktop, one reviewer on a phone and one on a desktop, sign-in off, revoke, a server restart); owner-side threads and the fenced prompt: `tests/e2e/design-comment-threads-e2e.mjs`.

package/docs/deployment-guide.md

@@ -496,6 +496,16 @@ ppm logs -f                # provider errors are logged here
 If the CLI cannot be found, set `PPM_CLAUDE_CLI=/path/to/claude`. If the project has an `.env` with
 `ANTHROPIC_API_KEY`, see the SDK note above.
 
+### A server or unit an AI chat started stopped by itself
+With **Settings → AI Provider → Stop leftover processes after** set above 0, PPM stops what a
+chat's commands left running once the chat has been idle that long, and everything the chat
+started when it is deleted; `ppm.log` names each stop (`[chat-procs]`). Raise the limit or set it
+back to 0 (the default: nothing is stopped, only logged), or give a unit that must outlive the
+chat a slice of its own: `systemd-run --user --slice=app.slice …`. A restart of PPM also stops
+what chats' commands left running, at any setting, as stopping PPM's service always did; a unit
+started with `systemd-run --user` survives it. See `docs/architecture/ai-chat-and-providers.md` →
+Processes a chat leaves running.
+
 ### Terminal not working
 ```bash
 which bash zsh             # macOS/Linux
@@ -687,3 +697,14 @@ Private bytes are measured on Windows and Linux; on macOS those fields are absen
 3. **Logs:** `ppm logs -f` (`~/.ppm/ppm.log`)
 4. **Status:** `ppm status --json`
 5. **Known traps:** [`lessons-learned.md`](lessons-learned.md)
+
+## Minimal startup
+
+`ppm start --minimal` serves chat, file explorer, editor and Settings to every browser. It keeps projects,
+chat providers/accounts, uploads, authentication and remote access; skips extension hosts,
+scheduled agents, Jira watchers, PPMBot and database startup work. Non-chat WebSocket and
+workspace API endpoints return 403. Saved workspace tabs are retained for full mode.
+
+The supervisor preserves the mode across crashes and `ppm restart`. Changing a running
+instance requires `ppm down` followed by `ppm start --minimal` (or `ppm start` for full
+mode). This is a process option, not a saved global setting or browser toggle.

package/docs/system-architecture.md

@@ -10,6 +10,7 @@ deployment and the error/security posture. Subsystem detail lives beside it:
 | [Data & Storage](architecture/data-and-storage.md) | SQLite schema and access, database viewer, MCP server management, group-chat model |
 | [Workspace & UI](architecture/workspace-and-ui.md) | Workspace switching, editor, terminal, git, file service, Design mode, OS File Explorer, tab-host windows and Document PiP |
 | [Integrations](architecture/integrations.md) | PPMBot Telegram coordinator, Jira watcher auto-debug |
+| [Schedules](architecture/schedules.md) | Prompt and script schedules: tick and always-on processes, the `ctx` API, shareable templates |
 | [Plugins & Tracing](architecture/plugins-and-tracing.md) | *Design, not built.* The append-only session-event log (including browser errors) and the seam inventory behind "Everything is a Plugin. Every run is traceable." |
 
 ## High-Level Architecture

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hienlh/ppm",
-  "version": "0.23.24",
+  "version": "0.23.25",
   "description": "Personal Project Manager — mobile-first web IDE with AI assistance",
   "author": "hienlh",
   "license": "SEE LICENSE IN LICENSE",

package/src/cli/commands/autostart.ts

@@ -12,6 +12,7 @@ export function registerAutoStartCommands(program: Command): void {
     .option("-p, --port <port>", "Override port")
     .option("-s, --share", "(deprecated) Tunnel is now always enabled")
     .option("--profile <name>", "DB profile name")
+    .option("--minimal", "Start with chat, files, editor and settings")
     .action(async (options) => {
       const { enableAutoStart } = await import("../../services/autostart-register.ts");
 
@@ -24,6 +25,7 @@ export function registerAutoStartCommands(program: Command): void {
         host,
         share: !!options.share,
         profile: options.profile,
+        minimal: !!options.minimal,
       };
 
       try {

package/src/cli/commands/restart.ts

@@ -45,7 +45,7 @@ export async function restartServer(options: { force?: boolean }) {
       const { stopServer } = await import("./stop.ts");
       await stopServer({ kill: true });
       const { startServer } = await import("../../server/index.ts");
-      await startServer({ port: port ? String(port) : undefined, profile });
+      await startServer({ port: port ? String(port) : undefined, profile, minimal: status.minimalMode === true });
       return;
     }
 
@@ -177,6 +177,8 @@ export async function restartServer(options: { force?: boolean }) {
   // terminal (and its process group) to receive SIGHUP.
   const params = JSON.stringify({
     serverPid, port, host, serverScript,
+    // The mode belongs to the running PPM: a restart keeps it, as the supervisor's does.
+    minimal: status.minimalMode === true,
     // The server's own loopback port, distinct from `port` (the PUBLIC port,
     // owned by the edge forwarder). The worker must only ever reclaim this one:
     // force-killing whatever listens on the public port would kill the edge,
@@ -252,6 +254,7 @@ async function main() {
   const serverArgs = isCompiled
     ? ["__serve__", "0", "127.0.0.1"]
     : ["run", P.serverScript, "__serve__", "0", "127.0.0.1"];
+  if (P.minimal) serverArgs.push("--minimal");
 
   if (process.platform === "win32") {
     const bunExe = process.execPath.replace(/\\\\/g, "\\\\\\\\");

package/src/cli/commands/schedule-cmd-api.ts

@@ -0,0 +1,70 @@
+/** Shared by the `ppm schedule` commands: output helpers, and the running server's REST API. */
+import type { ScheduleStatusView } from "../../types/scheduler.ts";
+
+export const C = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  green: "\x1b[32m",
+  red: "\x1b[31m",
+  yellow: "\x1b[33m",
+  cyan: "\x1b[36m",
+  dim: "\x1b[2m",
+};
+
+export const fail = (msg: string): never => {
+  console.error(`${C.red}✗${C.reset} ${msg}`);
+  process.exit(1);
+};
+
+/** No PPM server answered: the command can only go to the database, or not run at all. */
+export class ServerDownError extends Error {}
+
+/**
+ * `/api<path>` on the PPM server of this CLI's config, signed in. Script schedules are changed
+ * through it, because only the server can start or stop their processes. Call after
+ * `configService.load()`.
+ */
+export async function serverApi<T>(method: string, path: string, body?: unknown): Promise<T> {
+  const { configService } = await import("../../services/config.service.ts");
+  const auth = configService.get("auth");
+  let res: Response;
+  try {
+    res = await fetch(`http://127.0.0.1:${configService.get("port")}/api${path}`, {
+      method,
+      headers: {
+        ...(auth.enabled && { Authorization: `Bearer ${auth.token}` }),
+        ...(body !== undefined && { "Content-Type": "application/json" }),
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+      // A delete waits for the schedule's process to stop.
+      signal: AbortSignal.timeout(30_000),
+    });
+  } catch {
+    throw new ServerDownError("PPM server not running — start with 'ppm start'");
+  }
+  const json = await res.json().catch(() => null) as { ok?: boolean; data?: T; error?: string } | null;
+  if (!json?.ok) throw new Error(json?.error ?? `HTTP ${res.status}`);
+  return json.data as T;
+}
+
+/** `serverApi`, failing the command on any error. */
+export async function api<T>(method: string, path: string, body?: unknown): Promise<T> {
+  try {
+    return await serverApi<T>(method, path, body);
+  } catch (e) {
+    return fail((e as Error).message);
+  }
+}
+
+/** What a script schedule's process is doing, in a few words; empty when there is nothing to say. */
+export function statusText(s: ScheduleStatusView): string {
+  switch (s.state) {
+    case "running": return `${C.green}running${C.reset}${s.pid ? ` (pid ${s.pid})` : ""}`;
+    case "restarting": return `${C.yellow}restarting${s.restartAt ? ` at ${new Date(s.restartAt).toLocaleTimeString()}` : ""}${C.reset}`;
+    case "failed": return `${C.red}failed${C.reset}${s.lastError ? `: ${s.lastError.split("\n")[0]!.slice(0, 80)}` : ""}`;
+    case "blocked": return `${C.red}blocked${C.reset}: previous process (pid ${s.pid}) is still running`;
+    case "starting":
+    case "stopping": return `${C.yellow}${s.state}${C.reset}`;
+    default: return "";
+  }
+}

package/src/cli/commands/schedule-cmd-template.ts

@@ -0,0 +1,134 @@
+/**
+ * `ppm schedule export|import|state|set-state`: schedules as shareable files, and a script's
+ * state. All of it goes through the running server. Nothing here prints a secret's value, not
+ * even in an error: a `--secret` pair is never echoed back.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import type { Command } from "commander";
+import { coerceInputValue, missingRequiredInputs } from "../../shared/schedule-inputs.ts";
+import { parseScheduleTemplate, serializeScheduleTemplate, type ScheduleTemplate } from "../../shared/schedule-template.ts";
+import type { ScheduleInputValue, ScheduleView } from "../../types/scheduler.ts";
+import { api, C, fail } from "./schedule-cmd-api.ts";
+
+const collect = (value: string, previous: string[]) => [...previous, value];
+
+export interface ImportOptions {
+  project: string;
+  set: string[];
+  secret: string[];
+  trust?: boolean;
+}
+
+/** The body of POST /api/schedules/import for `file`; throws on anything it cannot use. */
+export function importBody(file: string, opts: ImportOptions) {
+  let text: string;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch (e) {
+    throw new Error(`Cannot read ${file}: ${(e as NodeJS.ErrnoException).code ?? (e as Error).message}`);
+  }
+  const parsed = parseScheduleTemplate(text);
+  if (!parsed.ok) throw new Error(`${file} is not a template PPM can import:\n  ${parsed.errors.join("\n  ")}`);
+  const decls = new Map((parsed.template.inputs ?? []).map((d) => [d.key, d]));
+  const inputValues: Record<string, ScheduleInputValue> = {};
+  for (const pair of opts.set) {
+    const [key, raw] = splitPair(pair, "--set");
+    const decl = decls.get(key);
+    if (!decl) throw new Error(`The template has no input named "${key}"`);
+    if (decl.type === "secret") throw new Error(`"${key}" is a secret; pass it with --secret`);
+    const value = coerceInputValue(decl, raw);
+    if (value instanceof Error) throw value;
+    inputValues[key] = value;
+  }
+  const secrets: Record<string, string> = {};
+  for (const pair of opts.secret) {
+    const [key, raw] = splitPair(pair, "--secret");
+    if (decls.get(key)?.type !== "secret") throw new Error(`The template has no secret input named "${key}"`);
+    secrets[key] = raw.startsWith("@") ? readSecretFile(raw.slice(1), key) : raw;
+  }
+  return { template: parsed.template, projectName: opts.project, inputValues, secrets, trust: opts.trust === true };
+}
+
+/** `key=value`. The pair is not quoted in the error: it may be a secret. */
+function splitPair(pair: string, flag: string): [string, string] {
+  const eq = pair.indexOf("=");
+  if (eq <= 0) throw new Error(`${flag} takes key=value`);
+  return [pair.slice(0, eq), pair.slice(eq + 1)];
+}
+
+/** A secret kept in a file, so it never sits in the shell's history; one trailing newline dropped. */
+function readSecretFile(path: string, key: string): string {
+  try {
+    return readFileSync(path, "utf8").replace(/\r?\n$/, "");
+  } catch (e) {
+    throw new Error(`Cannot read the file for the secret "${key}": ${(e as NodeJS.ErrnoException).code ?? "unreadable"}`);
+  }
+}
+
+export function registerScheduleTemplateCommands(schedule: Command, loadDeps: () => Promise<unknown>): void {
+  schedule
+    .command("export <id>")
+    .description("Write a schedule as a shareable template — never its secrets, state or history")
+    .option("-o, --output <file>", "Write to this file instead of standard output")
+    .action(async (id: string, opts: { output?: string }) => {
+      await loadDeps();
+      const { template, warnings } = await api<{ template: ScheduleTemplate; warnings: string[] }>("GET", `/schedules/${id}/export`);
+      const text = serializeScheduleTemplate(template);
+      if (opts.output) {
+        writeFileSync(opts.output, text);
+        console.error(`${C.green}✓${C.reset} Wrote ${opts.output}`);
+      } else {
+        process.stdout.write(text);
+      }
+      console.error(`${C.dim}Non-secret input values were included as defaults. Secrets were left out.${C.reset}`);
+      for (const warning of warnings) console.error(`${C.yellow}⚠${C.reset} ${warning}`);
+    });
+
+  schedule
+    .command("import <file>")
+    .description("Create a schedule from a template, turned off. Read its code before you trust it.")
+    .requiredOption("--project <name>", "Project it runs in")
+    .option("--set <key=value>", "Value of an input (repeatable)", collect, [])
+    .option("--secret <key=value|key=@file>", "Value of a secret input; @file reads it from a file (repeatable)", collect, [])
+    .option("--trust", "I have read this code and trust it to run on this machine")
+    .action(async (file: string, opts: ImportOptions) => {
+      await loadDeps();
+      let body: ReturnType<typeof importBody>;
+      try {
+        body = importBody(file, opts);
+      } catch (e) {
+        return fail((e as Error).message);
+      }
+      if (!body.trust) fail(`Read the code in ${file} first, then pass --trust to say you trust it to run on this machine`);
+      const created = await api<ScheduleView>("POST", "/schedules/import", body);
+      console.log(`${C.green}✓${C.reset} Schedule ${C.bold}#${created.id}${C.reset} "${created.name}" imported, turned off`);
+      const missing = missingRequiredInputs(created.inputs, created.inputValues, created.secretsSet);
+      if (missing.length) console.log(`  Fill in ${missing.join(", ")} before turning it on`);
+      else console.log(`  Turn it on with: ppm schedule enable ${created.id}`);
+    });
+
+  schedule
+    .command("state <id>")
+    .description("Print a script schedule's state, secrets masked")
+    .action(async (id: string) => {
+      await loadDeps();
+      const { state } = await api<{ state: string | null }>("GET", `/schedules/${id}/state`);
+      console.log(state ?? `${C.dim}No state.${C.reset}`);
+    });
+
+  schedule
+    .command("set-state <id> <file>")
+    .description("Replace a script schedule's state with a JSON file; the schedule must be off")
+    .action(async (id: string, file: string) => {
+      await loadDeps();
+      let state: unknown;
+      try {
+        state = JSON.parse(readFileSync(file, "utf8"));
+      } catch (e) {
+        // Not the parser's message: it quotes the text it stopped at, which may be a token.
+        return fail(`${file} ${(e as NodeJS.ErrnoException).code ? "cannot be read" : "is not valid JSON"}`);
+      }
+      await api("PUT", `/schedules/${id}/state`, { state });
+      console.log(`${C.green}✓${C.reset} State of schedule #${id} replaced`);
+    });
+}

package/src/cli/commands/schedule-cmd.ts

@@ -1,20 +1,9 @@
-/** `ppm schedule` CLI — manage scheduled Claude agents (cron). */
+/** `ppm schedule` CLI — manage scheduled Claude agents (cron) and script schedules. */
+import { readFileSync } from "node:fs";
 import { Command } from "commander";
-
-const C = {
-  reset: "\x1b[0m",
-  bold: "\x1b[1m",
-  green: "\x1b[32m",
-  red: "\x1b[31m",
-  yellow: "\x1b[33m",
-  cyan: "\x1b[36m",
-  dim: "\x1b[2m",
-};
-
-const fail = (msg: string): never => {
-  console.error(`${C.red}✗${C.reset} ${msg}`);
-  process.exit(1);
-};
+import type { ScheduleView } from "../../types/scheduler.ts";
+import { api, C, fail, serverApi, ServerDownError, statusText } from "./schedule-cmd-api.ts";
+import { registerScheduleTemplateCommands } from "./schedule-cmd-template.ts";
 
 async function loadDeps() {
   const { configService } = await import("../../services/config.service.ts");
@@ -23,30 +12,62 @@ async function loadDeps() {
   return { configService, db };
 }
 
+/**
+ * A script schedule's process is the server's: a change to one goes through the server, which
+ * starts or stops it. With no server running there is no process, and the database will do.
+ */
+async function viaServer(kind: string, method: string, path: string, body?: unknown): Promise<boolean> {
+  if (kind !== "script") return false;
+  try {
+    await serverApi(method, path, body);
+    return true;
+  } catch (e) {
+    if (e instanceof ServerDownError) return false;
+    return fail((e as Error).message);
+  }
+}
+
 export function registerScheduleCommands(program: Command): void {
-  const schedule = program.command("schedule").description("Scheduled Claude agents (cron)");
+  const schedule = program.command("schedule").description("Scheduled Claude agents (cron) and script schedules");
 
   schedule
     .command("add")
-    .description("Add a scheduled agent. Cron uses local timezone. Do not embed secrets in --prompt.")
+    .description("Add a scheduled agent (--prompt) or a script schedule (--script). Cron uses local timezone. Do not embed secrets in --prompt.")
     .requiredOption("--name <name>", "Schedule name")
-    .requiredOption("--cron <expr>", "Cron expression (local timezone, e.g. \"0 7 * * *\")")
+    .option("--cron <expr>", "Cron expression (local timezone, e.g. \"0 7 * * *\"; a script may add seconds first)")
     .requiredOption("--project <nameOrPath>", "Project name or path")
-    .requiredOption("--prompt <text>", "Prompt sent to the agent each run")
+    .option("--prompt <text>", "Prompt sent to the agent each run")
+    .option("--script <file>", "JavaScript module run each tick, or kept running (needs a running PPM server)")
+    .option("--mode <mode>", "Script mode: tick (on the cron) or always-on", "tick")
     .option("--permission-mode <mode>", "Permission mode", "bypassPermissions")
-    .option("--max-turns <n>", "Max turns per run")
-    .option("--timeout <ms>", "Timeout per run in ms", "1800000")
+    .option("--max-turns <n>", "Max turns per run (prompt only)")
+    .option("--timeout <ms>", "Timeout per run in ms (default 1800000 for a prompt, 300000 for a script tick)")
     .option("--disabled", "Create disabled")
     .action(async (opts) => {
       try {
         const { configService, db } = await loadDeps();
-        const { Cron } = await import("croner");
-        try { new Cron(opts.cron); } catch (e) { fail(`Invalid cron: ${(e as Error).message}`); }
-
         const { getProjects } = await import("../../services/db.service.ts");
         const project = getProjects().find((p) => p.name === opts.project || p.path === opts.project);
         if (!project) fail(`Project not found: ${opts.project}`);
 
+        if (opts.script) {
+          if (opts.prompt || opts.maxTurns) fail("--prompt and --max-turns are for a prompt schedule, not --script");
+          let script = "";
+          try { script = readFileSync(opts.script, "utf8"); } catch { fail(`Cannot read ${opts.script}`); }
+          const created = await api<ScheduleView>("POST", "/schedules", {
+            name: opts.name, kind: "script", mode: opts.mode, project_path: project!.path, script,
+            permission_mode: opts.permissionMode, enabled: !opts.disabled,
+            ...(opts.cron && { cron_expr: opts.cron }),
+            ...(opts.timeout && { timeout_ms: Number(opts.timeout) }),
+          });
+          console.log(`${C.green}✓${C.reset} Schedule ${C.bold}#${created.id}${C.reset} created (${opts.mode}${created.next_fire_at ? `, next fire: ${created.next_fire_at}` : ""})`);
+          return;
+        }
+        if (!opts.prompt || !opts.cron) fail("--prompt and --cron are required (or --script for a script schedule)");
+        if (opts.mode !== "tick") fail("A prompt schedule runs on its cron; --mode is for --script");
+        const { Cron } = await import("croner");
+        try { new Cron(opts.cron); } catch (e) { fail(`Invalid cron: ${(e as Error).message}`); }
+
         const id = db.insertSchedule({
           name: opts.name,
           cron_expr: opts.cron,
@@ -73,11 +94,17 @@ export function registerScheduleCommands(program: Command): void {
       const { db } = await loadDeps();
       const rows = db.getSchedules(!!opts.enabledOnly);
       if (rows.length === 0) { console.log(`${C.dim}No schedules.${C.reset}`); return; }
+      // What the processes are doing is only known to the server; without one, the list says less.
+      const live = await serverApi<ScheduleView[]>("GET", "/schedules").then((views) => new Map(views.map((v) => [v.id, v.status])), () => null);
       for (const s of rows) {
         const status = s.enabled ? `${C.green}enabled${C.reset}` : `${C.dim}disabled${C.reset}`;
         const lastRun = db.listScheduleRuns(s.id, 1)[0];
         const last = lastRun ? `last: ${lastRun.status}` : "never run";
-        console.log(`${C.bold}#${s.id}${C.reset} ${s.name}  ${C.cyan}${s.cron_expr}${C.reset}  ${status}  next: ${s.next_fire_at ?? "—"}  ${C.dim}${last} · ${s.project_path}${C.reset}`);
+        const kind = s.kind === "script" ? `script/${s.mode}` : "prompt";
+        const when = s.mode === "always-on" ? "" : `  ${C.cyan}${s.cron_expr}${C.reset}  next: ${s.next_fire_at ?? "—"}`;
+        const state = live?.get(s.id);
+        const doing = state ? statusText(state) : "";
+        console.log(`${C.bold}#${s.id}${C.reset} ${s.name}  ${kind}${when}  ${status}${doing ? `  ${doing}` : ""}  ${C.dim}${last} · ${s.project_path}${C.reset}`);
       }
     });
 
@@ -93,7 +120,10 @@ export function registerScheduleCommands(program: Command): void {
         const { confirm } = await import("@inquirer/prompts");
         if (!(await confirm({ message: `Delete schedule #${id} "${s!.name}" and its run history?` }))) return;
       }
-      db.deleteSchedule(Number(id));
+      if (!(await viaServer(s!.kind, "DELETE", `/schedules/${id}`))) {
+        db.deleteSchedule(Number(id));
+        if (s!.kind === "script") (await import("../../services/schedule-script/script-files.ts")).removeRunDir(Number(id));
+      }
       console.log(`${C.green}✓${C.reset} Schedule #${id} deleted`);
     });
 
@@ -106,12 +136,14 @@ export function registerScheduleCommands(program: Command): void {
         const s = db.getSchedule(Number(id));
         if (!s) fail(`Schedule not found: ${id}`);
         const enabling = action === "enable";
-        const { Cron } = await import("croner");
-        db.updateSchedule(Number(id), {
-          enabled: enabling ? 1 : 0,
-          // Recompute on enable so it doesn't fire immediately off a stale timestamp
-          ...(enabling && { next_fire_at: new Cron(s!.cron_expr).nextRun()?.toISOString() ?? null }),
-        });
+        if (!(await viaServer(s!.kind, "PATCH", `/schedules/${id}`, { enabled: enabling }))) {
+          const { Cron } = await import("croner");
+          db.updateSchedule(Number(id), {
+            enabled: enabling ? 1 : 0,
+            // Recompute on enable so it doesn't fire immediately off a stale timestamp
+            ...(enabling && s!.mode === "tick" && { next_fire_at: new Cron(s!.cron_expr).nextRun()?.toISOString() ?? null }),
+          });
+        }
         console.log(`${C.green}✓${C.reset} Schedule #${id} ${action}d`);
       });
   }
@@ -120,26 +152,13 @@ export function registerScheduleCommands(program: Command): void {
     .command("run-now <id>")
     .description("Fire a schedule immediately (requires running PPM server)")
     .action(async (id: string) => {
-      const { configService } = await loadDeps();
-      const port = configService.get("port");
-      const auth = configService.get("auth");
-      try {
-        const res = await fetch(`http://127.0.0.1:${port}/api/schedules/${id}/run-now`, {
-          method: "POST",
-          headers: auth.enabled ? { Authorization: `Bearer ${auth.token}` } : {},
-          signal: AbortSignal.timeout(5000),
-        });
-        const body = await res.json() as { ok: boolean; data?: { runId: number; wasRunning: boolean }; error?: string };
-        if (!body.ok) fail(body.error ?? `HTTP ${res.status}`);
-        console.log(`${C.green}✓${C.reset} Run ${C.bold}#${body.data!.runId}${C.reset} started`);
-        if (body.data!.wasRunning) {
-          console.log(`${C.yellow}⚠${C.reset} A previous run was still active — both now run concurrently`);
-        }
-      } catch (e) {
-        if (e instanceof Error && (e.name === "TimeoutError" || e.message.includes("fetch"))) {
-          fail("PPM server not running — start with 'ppm start'");
-        }
-        fail(e instanceof Error ? e.message : String(e));
+      const { db } = await loadDeps();
+      const data = await api<{ runId: number | null; wasRunning: boolean }>("POST", `/schedules/${id}/run-now`);
+      // A script tick keeps a run only if it has something to show, so it has no number yet.
+      if (data.runId !== null) console.log(`${C.green}✓${C.reset} Run ${C.bold}#${data.runId}${C.reset} started`);
+      else console.log(`${C.green}✓${C.reset} Schedule #${id} ${db.getSchedule(Number(id))?.mode === "always-on" ? "restarting" : "tick started"}`);
+      if (data.wasRunning && data.runId !== null) {
+        console.log(`${C.yellow}⚠${C.reset} A previous run was still active — both now run concurrently`);
       }
     });
 
@@ -159,4 +178,6 @@ export function registerScheduleCommands(program: Command): void {
         console.log(`${C.bold}#${r.id}${C.reset} ${color}${r.status}${C.reset}  ${r.started_at} → ${r.ended_at ?? "…"}${cost}${errHead}`);
       }
     });
+
+  registerScheduleTemplateCommands(schedule, loadDeps);
 }

package/src/cli/commands/status.ts

@@ -4,6 +4,7 @@ import { getPpmDir } from "../../services/ppm-dir.ts";
 import { redactSecrets } from "../../services/redact-secrets.ts";
 
 interface DaemonStatus {
+  minimalMode: boolean;
   running: boolean;
   pid: number | null;
   port: number | null;
@@ -36,7 +37,7 @@ async function probeHealth(port: number): Promise<boolean> {
 
 function getDaemonStatus(): DaemonStatus {
   const dead: DaemonStatus = {
-    running: false, pid: null, port: null, host: null,
+    minimalMode: false, running: false, pid: null, port: null, host: null,
     shareUrl: null, tunnelPid: null, tunnelAlive: false,
     supervisorPid: null, supervisorAlive: false,
     state: null, pausedAt: null, pauseReason: null, lastCrashError: null,
@@ -53,6 +54,7 @@ function getDaemonStatus(): DaemonStatus {
       const supervisorAlive = supervisorPid ? isAlive(supervisorPid) : false;
       return {
         running: isAlive(pid),
+        minimalMode: data.minimalMode === true,
         pid,
         port: data.port,
         host: data.host,
@@ -186,6 +188,7 @@ export async function showStatus(options: { json?: boolean; all?: boolean }) {
   if (status.supervisorPid) {
     console.log(`  Supervisor: ${status.supervisorAlive ? "running" : "stopped"} (PID: ${status.supervisorPid})`);
   }
+  console.log(`  Mode:    ${status.minimalMode ? "minimal (chat + editor)" : "full"}`);
   // Show state info
   const state = status.state ?? (status.running ? "running" : "stopped");
   if (state === "paused") {