@saadnvd1/agent-os 0.3.477 → 0.3.481

package/lib/orchestrator/serve.ts

@@ -26,6 +26,9 @@ import { readSession } from "./read";
 import { reviewTarget, signOffTarget } from "./external-gates";
 import { land } from "./signoff";
 import { arm, disarm } from "./armed";
+import { quickChange, quickPR } from "./quick";
+import { review } from "./review";
+import { cancelReminder, listReminders, remindMe } from "./reminders";
 import { parseArgs as p, type ToolName } from "./tool-schemas";
 
 export { isToolName, TOOLS, type ToolName } from "./tool-schemas";
@@ -37,6 +40,8 @@ const ACTING = new Set<ToolName>([
   "start_task",
   "set_task_model",
   "start_session",
+  "quick_change",
+  "quick_pr",
   "stack",
   "land",
   "drop",
@@ -119,6 +124,19 @@ export async function runTool(
         view: a.view,
       });
     }
+    case "quick_change": {
+      const a = p(tool, raw);
+      return quickChange(w, a.project, a.name);
+    }
+    case "quick_pr": {
+      const a = p(tool, raw);
+      const opened = await quickPR(w, a.change, a.title, a.body);
+      // Its code-review gate is this review: it starts at once.
+      const reviewing = await review(w, opened.id).catch(
+        (e: Error) => `Its review couldn't start (${e.message}): call review.`
+      );
+      return `${opened.text}\n${reviewing}`;
+    }
     case "stack": {
       const a = p(tool, raw);
       return stack(w, a.target, a.plan_only);
@@ -152,6 +170,14 @@ export async function runTool(
       addNote(w, `Removed standing rule ${rule.id}: ${rule.text}`);
       return `Rule ${rule.id} removed.`;
     }
+    case "remind_me": {
+      const a = p(tool, raw);
+      return remindMe(w, a.at, a.prompt, a.name);
+    }
+    case "reminders":
+      return listReminders(w);
+    case "cancel_reminder":
+      return cancelReminder(w, p(tool, raw).id);
     case "review": {
       const a = p(tool, raw);
       return reviewTarget(w, a.target, { fresh: a.fresh });

package/lib/orchestrator/signoff.ts

@@ -15,6 +15,7 @@ import { getStack, landInBackground } from "../stacks";
 import { LAND_DEFAULTS } from "../stacks/land";
 import { db, stackQueries, type Session } from "../db";
 import { getCheck } from "./checks";
+import { isQuick, quickCodeReview } from "./quick";
 import {
   addedLines,
   changedFiles,
@@ -82,6 +83,22 @@ export async function judge(
     };
   const sha = pr.head;
   const repo = repoOf(task);
+  // A PR quick_pr opened (by the row AgentOS wrote, never the body): its
+  // code review is the independent review of this head, and until that
+  // passes it waits, before any gate is judged or counted.
+  const quick = isQuick(task)
+    ? quickCodeReview(
+        sha,
+        getCheck(task.id, sha, "review"),
+        restackedOf(task)?.to === sha
+      )
+    : null;
+  if (quick?.wait)
+    return {
+      ok: false,
+      wait: true,
+      text: `${task.name} (PR #${pr.number} at ${short(sha)}) can't merge yet: ${quick.wait}`,
+    };
   return gateVerdict(
     workspaceId,
     { id: task.id, name: task.name, repo, refs: task, pr, sha },
@@ -100,12 +117,17 @@ export async function judge(
       fromCard: !!task.lh_card_id,
       scope: getCheck(task.id, sha, "scope"),
       stackRefusal: landing ? null : signOffRefusal(task.id),
-      codeReview: codeReviewGate({
-        head: sha,
-        attribution: pr.attribution,
-        review: (at) => getCheck(task.id, at, "review"),
-        restacked: restackedOf(task),
-      }),
+      codeReview: (() => {
+        const gate = codeReviewGate({
+          head: sha,
+          attribution: pr.attribution,
+          review: (at) => getCheck(task.id, at, "review"),
+          restacked: restackedOf(task),
+        });
+        // A quick change keeps the body checks (attribution, unreadable);
+        // its wait on the review was judged above.
+        return quick ? { refusal: gate.refusal, wait: null } : gate;
+      })(),
     }),
     opts
   );

package/lib/orchestrator/task-state.ts

@@ -17,6 +17,8 @@ import { untrusted } from "./untrusted";
 export async function waitingState(
   task: Session
 ): Promise<{ blocked: string | null; waitingOn: string | null }> {
+  // A quick change has no agent to block or ask: the orchestrator makes it.
+  if (task.quick_of) return { blocked: null, waitingOn: null };
   // A linked machine's chat lives in that machine's store, not this one's:
   // its own reading of the task is asked for, fresh.
   const link = hostLink(task.host_id);

package/lib/orchestrator/tool-names.ts

@@ -16,6 +16,8 @@ export const TOOL_NAMES = {
   start_task: name("start_task"),
   set_task_model: name("set_task_model"),
   start_session: name("start_session"),
+  quick_change: name("quick_change"),
+  quick_pr: name("quick_pr"),
   stack: name("stack"),
   stack_status: name("stack_status"),
   land: name("land"),
@@ -30,6 +32,9 @@ export const TOOL_NAMES = {
   sign_off: name("sign_off"),
   arm: name("arm"),
   disarm: name("disarm"),
+  remind_me: name("remind_me"),
+  reminders: name("reminders"),
+  cancel_reminder: name("cancel_reminder"),
   ask_saad: name("ask_saad"),
 } as const;
 
@@ -39,8 +44,11 @@ export const TOOL_NAMES = {
 // braked; the shell keeps only `aos` commands that read, and notify, which
 // reaches only Saad, so `aos send`, `task`, `spawn` and `stack` can't go
 // around them. It writes files, but never in a project repository, a task
-// worktree, AgentOS's own state or a secret file: its worker checks each
-// write first (write-guard.ts).
+// worktree, AgentOS's own state or a secret file, except inside its own
+// quick changes' worktrees (quick.ts), where it may also run git that
+// looks, stages or undoes, never commits with hooks or pushes: its worker
+// checks each write and each shell command first (write-guard.ts,
+// git-guard.ts).
 export const ORCHESTRATOR_PERMISSIONS: {
   permissionMode: PermissionMode;
   allowedTools: string[];
@@ -67,6 +75,8 @@ export const ORCHESTRATOR_PERMISSIONS: {
     "Bash(aos notify:*)",
     "Bash(aos docs:*)",
     "Bash(aos doc:*)",
+    // Only `git -C <its own quick worktree>`, refused anywhere else.
+    "Bash(git:*)",
   ],
   disallowedTools: [],
 };

package/lib/orchestrator/tool-schemas.ts

@@ -135,6 +135,32 @@ export const TOOL_SHAPES = {
       .describe("A short name, 2-6 words (default: one made from the prompt)"),
     view,
   },
+  quick_change: {
+    project,
+    name: z
+      .string()
+      .trim()
+      .min(1)
+      .max(80)
+      .describe("A short name for the change, 2-6 words"),
+  },
+  quick_pr: {
+    change: ref("Your quick change, by name or id"),
+    title: z
+      .string()
+      .trim()
+      .min(1)
+      .max(200)
+      .describe("The PR's title, also its commit message"),
+    body: z
+      .string()
+      .trim()
+      .min(1)
+      .max(20000)
+      .describe(
+        "What changed and why; the review judges the change against it"
+      ),
+  },
   stack: {
     target: ref("Board or project name"),
     plan_only: z.boolean().optional(),
@@ -168,6 +194,23 @@ export const TOOL_SHAPES = {
       .describe("The rule, one sentence"),
   },
   rule_remove: { id: z.number().int().positive().describe("The rule's id") },
+  remind_me: {
+    at: z
+      .string()
+      .trim()
+      .min(1)
+      .max(100)
+      .describe('When: "tomorrow 10am", "in 2h" or 2026-10-12T10:00 (Central)'),
+    prompt: z
+      .string()
+      .trim()
+      .min(1)
+      .max(2000)
+      .describe("What to remind yourself of, in words you'll understand later"),
+    name: z.string().trim().min(1).max(80).optional(),
+  },
+  reminders: {},
+  cancel_reminder: { id: ref("The reminder's id, from reminders") },
   review: {
     target: ref("The task, or its PR (#12 or URL)"),
     fresh: z

package/lib/orchestrator/tools.ts

@@ -66,6 +66,10 @@ const DESCRIPTIONS: Record<ToolName, string> = {
     'Resume a paused task on another model ("provider/model", or a map of role to one), keeping its conversation and worktree; it\'s told to carry on (or message). Refused mid-turn.',
   start_session:
     "Start an interactive agent session in a project with a prompt. It runs as a chat unless view is terminal (only for a job that needs a TUI). Refused while a brake holds.",
+  quick_change:
+    "Make a small, low-risk edit yourself (a typo, a config value, a one-file fix): cuts a worktree and branch from the project's default branch and returns its path. You may write there (Write, Edit) and run git there as `git -C <path> ...` (status, diff, add, rm, mv, restore, reset, log, show); nowhere else in a project. Anything needing real work, tests or an investigation is a task (start_task).",
+  quick_pr:
+    "Commit everything in a quick change's worktree, push its branch (never the default branch) and open its PR, or push to the PR it already has. The PR goes through the same gates as a task's; with no task agent to run /do-code-review, its code-review gate is the independent review of its exact head, which starts now.",
   stack:
     "Run a LumifyHub board's open cards as stacked tasks (each start braked), or with plan_only just show the plan.",
   stack_status: "One stack's items, PRs and progress.",
@@ -80,6 +84,12 @@ const DESCRIPTIONS: Record<ToolName, string> = {
     'Keep a standing rule for this workspace, in your brief on every start from now on ("never merge #111", "briefs must not name third-party products"). It restricts or informs; it can never approve anything.',
   rule_remove:
     "Remove a standing rule you kept, by its id, only when Saad says so or it no longer applies (the PR it names merged or closed). Saad's rules are his to remove.",
+  remind_me:
+    "Set a one-off reminder for yourself in this workspace: at the time given it reaches you once as a scheduled prompt (not an approval), even if AgentOS was off then. At least 10 minutes ahead; a few at a time at most.",
+  reminders:
+    "List this workspace's upcoming reminders and the last few that ran.",
+  cancel_reminder:
+    "Cancel a reminder you set, by its id from reminders. Reminders Saad made are his to change.",
   review:
     "Start an independent read-only review of a PR at its exact head commit, or read the stored verdict for that commit. Takes a task, or any open PR in a workspace repository by #N, owner/repo#N or URL, even one no task owns.",
   sign_off:

package/lib/orchestrator/write-guard.ts

@@ -21,6 +21,8 @@ import { isSecretPath } from "../secret-paths";
 import { WORKTREES_DIR } from "../worktrees";
 import { orchestratorDir } from "./home";
 import { LIMITS_FILE } from "./usage";
+import { GIT_LAYOUT_FILE, readCommand } from "./git-guard";
+import { quickWorktrees } from "./quick-store";
 
 // The tools that write a file, and the argument naming it.
 export const WRITE_TOOLS: Record<string, string> = {
@@ -43,6 +45,9 @@ export interface WriteBounds {
   home: string;
   // Folders whose files run (~/Library, PATH, the usage brake's input...).
   runs: string[];
+  // Its own quick changes' worktrees (quick.ts): the one place in a
+  // project it may write, everything else in `repos` still refused.
+  quick?: string[];
 }
 
 // Wherever they are, files that configure what an agent, git or a
@@ -129,6 +134,7 @@ export async function writeRefusal(
   let ownDir: string[];
   let home: string[];
   let runs: string[];
+  let quick: string[][];
   try {
     // Where it lands as written, and with `..` taken by name first, as a
     // tool that normalises the path before opening it would; and where it
@@ -151,16 +157,27 @@ export async function writeRefusal(
     state = await both(bounds.state);
     ownDir = await both(bounds.ownDir);
     home = await both(bounds.home);
+    quick = await Promise.all((bounds.quick ?? []).map(both));
   } catch (e) {
     return `Couldn't resolve ${filePath}: ${(e as Error).message}.`;
   }
   for (const target of targets) {
-    const repo = repos.find((r) => within(target, r));
+    // Inside one of its quick worktrees, the roots that hold that worktree
+    // (the worktrees folder, a project above it) don't count; any other
+    // root, one nested inside it included, still refuses.
+    const ownQuick = quick.find((q) => q.some((d) => within(target, d)));
+    const holdsQuick = (r: string) =>
+      !!ownQuick && ownQuick.some((d) => within(d, r));
+    const repo = repos.find((r) => within(target, r) && !holdsQuick(r));
     if (repo)
-      return `${filePath} is inside ${repo}, a project repository, task worktree or AgentOS itself. Change code there through a task (start_task), so its PR goes through the merge gates.`;
+      return `${filePath} is inside ${repo}, a project repository, task worktree or AgentOS itself. Change code there through a task (start_task), or for a small edit, in a quick change's worktree (quick_change), so its PR goes through the merge gates.`;
+    if (ownQuick && GIT_LAYOUT_FILE.test(target))
+      return `${filePath} is part of a git repository's layout (HEAD, .git/, .gitattributes); git config can run programs, so orchestrators never write those.`;
     if (AGENTOS_TEMP.test(target))
       return `${filePath} is in a checkout AgentOS is reviewing or rebasing; orchestrators never write there.`;
-    const own = ownDir.some((d) => within(target, d));
+    // Its folder, or a quick worktree (which sits in ~/.agent-os/worktrees):
+    // AgentOS's state and the home's dot-folders hold it, but it's its own.
+    const own = ownDir.some((d) => within(target, d)) || !!ownQuick;
     if (state.some((d) => within(target, d)) && !own)
       return `${filePath} is in AgentOS's own state (${bounds.state}); you may write only in your folder, ${bounds.ownDir}.`;
     if (isSecretPath(target) || isSecretPath(filePath))
@@ -219,6 +236,7 @@ export async function orchestratorWriteBounds(
       ...(process.env.PATH ?? "").split(":").filter((d) => d.startsWith("/")),
     ],
     ownDir: orchestratorDir(session.workspace_id ?? ""),
+    quick: quickWorktrees(session.id),
     state: path.join(os.homedir(), ".agent-os"),
     repos: [...repos, WORKTREES_DIR, process.cwd(), path.dirname(dbPath)],
   };
@@ -287,9 +305,68 @@ export async function orchestratorToolRefusal(
   tool: string,
   input: Record<string, unknown>
 ): Promise<string | null> {
+  if (tool === "Bash") return commandRefusal(session, input.command);
   const arg = WRITE_TOOLS[tool];
   if (!arg) return null;
   const filePath = input[arg];
   if (typeof filePath !== "string") return "No file path to check.";
   return writeRefusal(filePath, await orchestratorWriteBounds(session));
 }
+
+// A shell command: one plain command, and git only in its own quick
+// worktrees (git-guard.ts), the folder it names resolved like a write's.
+async function commandRefusal(
+  session: Session,
+  command: unknown
+): Promise<string | null> {
+  const read = readCommand(command);
+  if (read.refusal !== null || read.dir === null) return read.refusal;
+  const quick = quickWorktrees(session.id);
+  const dir = read.dir;
+  if (!dir.startsWith("/") || !quick.length)
+    return `Refused: git runs only in one of your quick changes' worktrees, named by its full path (${quick.length ? quick.join(", ") : "you have none open; start one with quick_change"}).`;
+  return (await isQuickRoot(dir, quick))
+    ? null
+    : `Refused: ${read.dir} isn't the root of one of your quick changes' worktrees (${quick.join(", ")}). Git runs at the root only, never in a subfolder, a project checkout or another session's worktree.`;
+}
+
+// Whether a folder is inside one of these worktrees by every way the
+// system could read it: as named, with `..` taken by name, and with links
+// followed.
+export async function insideQuick(
+  dir: string,
+  quick: string[]
+): Promise<boolean> {
+  try {
+    const forms = [
+      path.resolve(dir),
+      await physicalPath(dir),
+      await physicalPath(path.resolve(dir)),
+    ];
+    const roots = (
+      await Promise.all(
+        quick.map(async (q) => [path.resolve(q), await physicalPath(q)])
+      )
+    ).flat();
+    return forms.every((f) => roots.some((r) => within(f, r)));
+  } catch {
+    return false;
+  }
+}
+
+// Whether a folder is exactly the root of one of these worktrees (as named,
+// and with links followed), where git finds the real git dir.
+async function isQuickRoot(dir: string, quick: string[]): Promise<boolean> {
+  if (!(await insideQuick(dir, quick))) return false;
+  try {
+    const forms = [path.resolve(dir), await physicalPath(dir)];
+    const roots = (
+      await Promise.all(
+        quick.map(async (q) => [path.resolve(q), await physicalPath(q)])
+      )
+    ).flat();
+    return forms.every((f) => roots.includes(f));
+  } catch {
+    return false;
+  }
+}

package/lib/schedules/badge.ts

@@ -5,14 +5,24 @@ export interface SchedulesBadge {
   next: { name: string; at: number; timezone: string } | null;
   // How many schedules' last run failed.
   failed: number;
+  // Enabled one-offs still to run, soonest first.
+  upcoming: number;
+  nextUpcoming: { name: string; at: number; timezone: string } | null;
 }
 
 // What the sidebar's Schedules clock says at a glance.
 export function schedulesBadge(schedules: ScheduleView[]): SchedulesBadge {
   let next: SchedulesBadge["next"] = null;
   let failed = 0;
+  let upcoming = 0;
+  let nextUpcoming: SchedulesBadge["nextUpcoming"] = null;
   for (const s of schedules) {
     if (s.lastRun?.outcome === "failed") failed++;
+    if (s.oneOff && s.enabled && !s.done_at) {
+      upcoming++;
+      if (s.nextRunAt && (!nextUpcoming || s.nextRunAt < nextUpcoming.at))
+        nextUpcoming = { name: s.name, at: s.nextRunAt, timezone: s.timezone };
+    }
     if (
       s.enabled &&
       !s.paused &&
@@ -21,5 +31,5 @@ export function schedulesBadge(schedules: ScheduleView[]): SchedulesBadge {
     )
       next = { name: s.name, at: s.nextRunAt, timezone: s.timezone };
   }
-  return { next, failed };
+  return { next, failed, upcoming, nextUpcoming };
 }

package/lib/schedules/cron.ts

@@ -100,7 +100,7 @@ export function isTimezone(tz: string): boolean {
 }
 
 const formatters = new Map<string, Intl.DateTimeFormat>();
-function wall(ms: number, tz: string) {
+export function wall(ms: number, tz: string) {
   let f = formatters.get(tz);
   if (!f) {
     f = new Intl.DateTimeFormat("en-US", {

package/lib/schedules/index.ts

@@ -7,7 +7,13 @@
 
 import { getProject } from "../projects";
 import { resolveSession } from "../bus";
-import { describeCron, everyCron } from "./cron";
+import {
+  DEFAULT_TIMEZONE,
+  describeCron,
+  everyCron,
+  formatRunTime,
+} from "./cron";
+import { parseWhen } from "./when";
 import { runSlot, type RunDeps, type RunResult } from "./run";
 import { nextRunAt } from "./scheduler";
 import { realDeps } from "./start";
@@ -37,12 +43,28 @@ export interface ScheduleView extends Schedule {
   lastRun: ScheduleRun | null;
   // Its workspace's orchestrator is paused, so it skips its slots.
   paused: boolean;
+  oneOff: boolean;
+  // Who made it: Saad, or the agent session (the orchestrator, or another).
+  createdBy: { kind: "saad" | "orchestrator" | "session"; name: string };
+}
+
+function creatorOf(s: Schedule): ScheduleView["createdBy"] {
+  const creator = s.created_by_session_id
+    ? getSessionRow(s.created_by_session_id)
+    : null;
+  if (!creator) return { kind: "saad", name: "Saad" };
+  return creator.role === "orchestrator"
+    ? { kind: "orchestrator", name: "Orchestrator" }
+    : { kind: "session", name: creator.name };
 }
 
 export function scheduleView(s: Schedule, now = Date.now()): ScheduleView {
   return {
     ...s,
-    description: describeCron(s.cron),
+    description:
+      s.run_at != null
+        ? `Once, ${formatRunTime(s.run_at, s.timezone)}`
+        : describeCron(s.cron),
     projectName: s.project_id ? (getProject(s.project_id)?.name ?? null) : null,
     targetName: s.target_session_id
       ? (getSessionRow(s.target_session_id)?.name ?? null)
@@ -50,6 +72,8 @@ export function scheduleView(s: Schedule, now = Date.now()): ScheduleView {
     nextRunAt: nextRunAt(s, now),
     lastRun: lastRun(s.id),
     paused: isPaused(s.workspace_id),
+    oneOff: s.run_at != null,
+    createdBy: creatorOf(s),
   };
 }
 
@@ -65,6 +89,8 @@ export function checkInInput(opts: {
   from?: string | null;
   every?: string;
   cron?: string;
+  // A one-off instead of a cron: "tomorrow 10am", "in 2h", an ISO time.
+  at?: string;
   prompt: string;
   name?: string;
   timezone?: string;
@@ -79,14 +105,26 @@ export function checkInInput(opts: {
     if (sessionWorkspace(creator) !== workspaceId)
       throw new Error(`${session.name} isn't in your workspace`);
   }
-  const cron = opts.cron?.trim() || everyCron(opts.every ?? "30m");
+  if (opts.at && (opts.cron || opts.every))
+    throw new Error("Give a run time (at) or a repeat (every, cron), not both");
+  const tz = opts.timezone?.trim() || DEFAULT_TIMEZONE;
+  const runAt = opts.at ? parseWhen(opts.at, tz) : null;
+  const cron =
+    runAt === null
+      ? opts.cron?.trim() || everyCron(opts.every ?? "30m")
+      : undefined;
   // The workspace's orchestrator is kept as "its orchestrator", not this
   // session's id: each run goes to whichever session is orchestrator then.
   const orchestrator = session.role === "orchestrator";
   return {
     workspaceId,
-    name: opts.name?.trim() || `Check-in: ${session.name}`.slice(0, 80),
+    name:
+      opts.name?.trim() ||
+      (runAt === null
+        ? `Check-in: ${session.name}`.slice(0, 80)
+        : reminderName(workspaceId, runAt, tz)),
     cron,
+    at: runAt,
     timezone: opts.timezone,
     prompt: opts.prompt,
     kind: orchestrator ? "orchestrator" : "message",
@@ -95,12 +133,30 @@ export function checkInInput(opts: {
   };
 }
 
+// "Reminder Tue, Oct 7, 9:00 AM", with a number after it when that's taken.
+export function reminderName(
+  workspaceId: string,
+  runAt: number,
+  tz = DEFAULT_TIMEZONE
+): string {
+  const taken = new Set(
+    listSchedules(workspaceId)
+      .filter((s) => !s.done_at)
+      .map((s) => s.name.toLowerCase())
+  );
+  const base = `Reminder ${formatRunTime(runAt, tz)}`;
+  let name = base;
+  for (let n = 2; taken.has(name.toLowerCase()); n++) name = `${base} (${n})`;
+  return name;
+}
+
 export function scheduleHistory(id: string, limit = 50): ScheduleRun[] {
   return listRuns(id, limit);
 }
 
 // Run now: its own slot, whatever the time and while the last run is still
-// working. Pause holds it like any run.
+// working. Pause holds it like any run. A one-off has one slot, so Run now
+// uses up its only run.
 export async function runNow(
   id: string,
   deps: RunDeps = realDeps
@@ -108,6 +164,11 @@ export async function runNow(
   const schedule = getSchedule(id);
   if (!schedule || schedule.archived_at) throw new Error("Schedule not found");
   const result = await runSlot(schedule, Date.now(), "manual", deps);
-  if (!result) throw new Error("Couldn't claim a run");
+  if (!result)
+    throw new Error(
+      schedule.run_at != null
+        ? "It already ran: edit it to a new time to run it again"
+        : "Couldn't claim a run"
+    );
   return result;
 }

package/lib/schedules/run.ts

@@ -3,6 +3,7 @@ import {
   attachSession,
   brakeRun,
   claimSlot,
+  finishOneOff,
   finishRun,
   lastSettledBefore,
   lastStarted,
@@ -60,8 +61,15 @@ export async function runSlot(
   trigger: RunTrigger,
   deps: RunDeps
 ): Promise<RunResult | null> {
+  // A one-off has one slot, Run now included: the claim is what stops it
+  // running twice.
+  const oneOff = schedule.run_at != null;
+  if (oneOff) slotAt = schedule.run_at!;
   const slot =
-    trigger === "manual" ? `manual:${randomUUID()}` : slotKey(slotAt);
+    trigger === "manual" && !oneOff
+      ? `manual:${randomUUID()}`
+      : slotKey(slotAt);
+  if (oneOff && schedule.done_at) return null;
   const runId = claimSlot(schedule.id, slot, slotAt, trigger);
   if (runId === null) return null;
   const caughtUp = trigger === "catch-up" ? "caught up" : null;
@@ -71,6 +79,7 @@ export async function runSlot(
     sessionId: string | null = null
   ): RunResult => {
     finishRun(runId, outcome, detail, sessionId);
+    if (oneOff) finishOneOff(schedule.id);
     return { runId, outcome, detail, sessionId };
   };
   const joined = (...parts: (string | null)[]) =>
@@ -90,6 +99,16 @@ export async function runSlot(
     return done("failed", why);
   };
 
+  // A recurring run skips while paused; a one-off has only this run, so it's
+  // held like a brake and runs once the workspace resumes.
+  const paused = (): RunResult => {
+    if (!oneOff)
+      return done("skipped", joined(caughtUp, "paused with the orchestrator"));
+    const detail = "held: paused with the orchestrator";
+    brakeRun(runId, detail);
+    return { runId, outcome: "skipped", detail, sessionId: null };
+  };
+
   // Its session is gone and won't come back: the schedule turns itself off
   // and says so once, instead of failing every slot.
   const gone = targetGone(schedule);
@@ -100,9 +119,8 @@ export async function runSlot(
   }
   const target = targetProblem(schedule);
   if (target) return fail(target);
-  if (pausedFor(schedule))
-    return done("skipped", joined(caughtUp, "paused with the orchestrator"));
-  if (trigger !== "manual") {
+  if (pausedFor(schedule)) return paused();
+  if (trigger !== "manual" && !oneOff) {
     const previous = lastStarted(schedule.id, runId);
     if (previous) {
       let busy: boolean;
@@ -128,8 +146,7 @@ export async function runSlot(
   }
 
   // Again: Saad may have paused while the overlap check waited.
-  if (pausedFor(schedule))
-    return done("skipped", joined(caughtUp, "paused with the orchestrator"));
+  if (pausedFor(schedule)) return paused();
   try {
     const started = await deps.start(schedule, (id) =>
       attachSession(runId, id)

package/lib/schedules/scheduler.ts

@@ -23,14 +23,24 @@ export const LATE_MS = 90 * 1000;
 
 // The slot a schedule is due to run now, if any.
 export function dueSlot(schedule: Schedule, now: number): number | null {
-  if (!schedule.enabled || schedule.archived_at) return null;
+  if (!schedule.enabled || schedule.archived_at || schedule.done_at)
+    return null;
+  // A one-off is due from its run time on, whenever AgentOS notices: no
+  // armed_at cut-off, so a run missed while it was off still happens.
+  if (schedule.run_at != null) {
+    if (schedule.run_at > now) return null;
+    return slotTaken(schedule.id, slotKey(schedule.run_at))
+      ? null
+      : schedule.run_at;
+  }
   const slot = prevRun(schedule.cron, now, schedule.timezone);
   if (slot === null || slot <= schedule.armed_at) return null;
   return slotTaken(schedule.id, slotKey(slot)) ? null : slot;
 }
 
 export function nextRunAt(schedule: Schedule, now = Date.now()): number | null {
-  if (!schedule.enabled) return null;
+  if (!schedule.enabled || schedule.done_at) return null;
+  if (schedule.run_at != null) return schedule.run_at;
   return nextRun(
     schedule.cron,
     Math.max(now, schedule.armed_at),