@saadnvd1/agent-os 0.3.662 → 0.3.671

package/lib/orchestrator/external-gates.ts

@@ -25,6 +25,9 @@ import { addNote } from "./notes";
 import { commitTime } from "./repo";
 import { review, reviewAt, type ReviewOpts } from "./review";
 import { gateVerdict, signOff, type Verdict } from "./signoff";
+import { fullAccessOn } from "./full-access";
+import { signOffTask } from "../tasks";
+import { prFor } from "../tasks/session";
 import { ciSettleIn } from "./task-state";
 import { untrusted } from "./untrusted";
 
@@ -186,14 +189,72 @@ export async function reviewExternal(
 // sign_off: a task, or a PR no task owns in one of the workspace's repos.
 export async function signOffTarget(
   workspaceId: string,
-  ref: string
+  ref: string,
+  opts: { direct?: boolean; reason?: string } = {}
 ): Promise<string> {
+  if (opts.direct) {
+    if (!fullAccessOn(workspaceId))
+      throw new Error(
+        "A direct merge needs Orchestrator full access (Settings → Workspaces); merge through the gates"
+      );
+    if (!opts.reason?.trim()) throw new Error("A direct merge needs a reason");
+    return signOffDirect(
+      workspaceId,
+      await gateTarget(workspaceId, ref),
+      opts.reason
+    );
+  }
   const t = await gateTarget(workspaceId, ref);
   return t.kind === "external"
     ? signOffExternal(workspaceId, t.pr)
     : signOff(workspaceId, t.task.id);
 }
 
+// Orchestrator full access: merge now at the PR's current head, skipping the
+// gates. The task's own non-gate checks still run (it's running, its PR is
+// open and on its base, the head is the one merged); a task with Saad (the
+// loop guard, no CI) is his to decide, not skipped here.
+async function signOffDirect(
+  workspaceId: string,
+  t: Awaited<ReturnType<typeof gateTarget>>,
+  reason: string
+): Promise<string> {
+  if (t.kind === "external") {
+    const { pr, method } = {
+      pr: t.pr,
+      method: mergePolicy(t.pr.project).method,
+    };
+    if (!pr.pr.head) throw new Error(`${pr.name}'s head commit is unknown`);
+    await mergePR({
+      repo: pr.repo,
+      number: pr.number,
+      slug: pr.slug,
+      method,
+      head: pr.pr.head,
+    });
+    resolveAsks(workspaceId, pr.id, `${pr.name} merged directly`);
+    addNote(
+      workspaceId,
+      `Merged ${pr.name} directly at ${short(pr.pr.head)}, skipping the gates: ${reason.trim()}`
+    );
+    return `Merged ${pr.name}: ${MERGED_AS[method]} at ${short(pr.pr.head)}, without the gates.`;
+  }
+  const task = t.task;
+  if (holdingEscalations(task.id).length)
+    throw new Error(
+      `${task.name} is with Saad; he signs it off or drops it, a direct merge doesn't go around that`
+    );
+  const pr = await prFor(task, true);
+  if (!pr || pr.state !== "OPEN" || !pr.head)
+    throw new Error(`${task.name} has no open PR`);
+  const method = await signOffTask(task.id, { head: pr.head });
+  addNote(
+    workspaceId,
+    `Merged ${task.name} directly (PR #${pr.number}, ${short(pr.head)}), skipping the gates: ${reason.trim()}`
+  );
+  return `Merged ${task.name}: PR #${pr.number} ${method ? MERGED_AS[method] : "merged"} at ${short(pr.head)}, without the gates.`;
+}
+
 // review: the same targets as sign_off.
 export async function reviewTarget(
   workspaceId: string,

package/lib/orchestrator/full-access.ts

@@ -0,0 +1,21 @@
+/**
+ * "Orchestrator full access" (Saad, 2026-10-18): a workspace's orchestrator
+ * runs with no shell deny list, no write limits, no quick-change cap, and
+ * may merge directly. Per workspace, on by default, switched in Settings →
+ * Workspaces; off restores every guard unchanged. Only an orchestrator
+ * session is ever judged by it: task agents, ordinary sessions, devices and
+ * other machines' callers are never loosened.
+ */
+
+import { getWorkspace } from "../workspaces";
+import type { Session } from "../db";
+
+export function fullAccessOn(workspaceId: string | null | undefined): boolean {
+  return !!workspaceId && !!getWorkspace(workspaceId)?.orch_full_access;
+}
+
+export function orchestratorFullAccess(
+  session: Pick<Session, "role" | "workspace_id">
+): boolean {
+  return session.role === "orchestrator" && fullAccessOn(session.workspace_id);
+}

package/lib/orchestrator/home.ts

@@ -5,10 +5,9 @@
  * sessions.
  */
 
+import { agentosHome } from "../agentos-home";
 import { resolveRoleOrDefault } from "../models/resolve";
 import fs from "fs";
-import os from "os";
-import path from "path";
 import { randomBytes, randomUUID, timingSafeEqual } from "crypto";
 import { db, type Session } from "../db";
 import { getWorkspace } from "../workspaces";
@@ -16,9 +15,7 @@ import { refuseRealStateUnderTest } from "../test-home-guard";
 
 // It works through tools, not in a repo: a scratch folder of its own.
 export const orchestratorDir = (workspaceId: string) =>
-  refuseRealStateUnderTest(
-    path.join(os.homedir(), ".agent-os", "orchestrators", workspaceId)
-  );
+  refuseRealStateUnderTest(agentosHome("orchestrators", workspaceId));
 
 export function getOrchestrator(workspaceId: string): Session | null {
   return (

package/lib/orchestrator/quick.ts

@@ -25,13 +25,16 @@ import { expandHome, forgetPR, prFor, projectPathFor } from "../tasks/session";
 import { inBackground } from "../lumifyhub/task-cards";
 import type { CheckRow } from "./checks";
 import { getOrchestrator } from "./home";
+import { fullAccessOn } from "./full-access";
+import { setupWorktree } from "../env-setup";
 import { addNote } from "./notes";
 import { quickWorktrees } from "./quick-store";
 import { findWorkspaceSession } from "./read";
 import { workspaceProject } from "./targets";
 import { recordPr, setTask } from "../db/session-parts";
 
-// Open quick changes one orchestrator may hold at once.
+// Open quick changes one orchestrator may hold at once, unless its workspace
+// has Orchestrator full access on (the default).
 export const MAX_OPEN_QUICK = 5;
 
 // Git with no hooks: a hook is a script in the project (or one it calls,
@@ -62,7 +65,13 @@ export async function startQuickChange(
   workspaceId: string,
   projectRef: string,
   name: string
-): Promise<{ id: string; worktreePath: string; text: string }> {
+): Promise<{
+  id: string;
+  worktreePath: string;
+  text: string;
+  // Dependencies and the project's setup, running in the background.
+  setup: Promise<void>;
+}> {
   const owner = ownerOf(workspaceId);
   const project = workspaceProject(workspaceId, projectRef);
   if (isRemoteHost(project.host_id))
@@ -70,7 +79,7 @@ export async function startQuickChange(
       `${project.name} runs on another machine; quick changes are made on this one only`
     );
   const open = quickWorktrees(owner.id);
-  if (open.length >= MAX_OPEN_QUICK)
+  if (!fullAccessOn(workspaceId) && open.length >= MAX_OPEN_QUICK)
     throw new Error(
       `You have ${open.length} quick changes open (${MAX_OPEN_QUICK} at most): finish one with quick_pr, or drop it, first`
     );
@@ -122,13 +131,47 @@ export async function startQuickChange(
     workspaceId,
     `Quick change "${label}" in ${project.name} on ${wt.branchName}.`
   );
+  const full = fullAccessOn(workspaceId);
+  const setup = installDependencies(
+    workspaceId,
+    label,
+    wt.worktreePath,
+    projectPath
+  );
+  inBackground(`setup of quick change ${id}`, () => setup);
   return {
     id,
     worktreePath: wt.worktreePath,
-    text: `Quick change "${label}" (id ${id.slice(0, 8)}) in ${project.name}: worktree ${wt.worktreePath} on ${wt.branchName}, cut from ${baseBranch}. Edit files there with Write and Edit; git there only as \`git -C ${wt.worktreePath} <status|diff|add|...>\`. Then quick_pr commits, pushes and opens its PR.`,
+    setup,
+    text: `Quick change "${label}" (id ${id.slice(0, 8)}) in ${project.name}: worktree ${wt.worktreePath} on ${wt.branchName}, cut from ${baseBranch}. Dependencies are installing in the background (a note says when they're ready). Edit files there with Write and Edit; ${full ? "run any git there" : "git there only as `git -C " + wt.worktreePath + " <status|diff|add|...>`"}. Then quick_pr commits, pushes and opens its PR.`,
   };
 }
 
+// The project's own worktree setup (dependencies, env files), so tests and
+// the build run in the quick change. One note when it ends.
+async function installDependencies(
+  workspaceId: string,
+  label: string,
+  worktreePath: string,
+  projectPath: string
+): Promise<void> {
+  try {
+    const r = await setupWorktree({ worktreePath, sourcePath: projectPath });
+    const failed = r.steps.find((s) => !s.success);
+    addNote(
+      workspaceId,
+      failed
+        ? `Quick change "${label}": setup failed at ${failed.name}: ${failed.error ?? "see its worktree"}.`
+        : `Quick change "${label}": dependencies installed, ready to build and test.`
+    );
+  } catch (e) {
+    addNote(
+      workspaceId,
+      `Quick change "${label}": setup failed: ${(e as Error).message}.`
+    );
+  }
+}
+
 // A quick change of this workspace's orchestrator, by name, id or PR.
 export function workspaceQuick(workspaceId: string, ref: string): Session {
   const owner = ownerOf(workspaceId);

package/lib/orchestrator/serve.ts

@@ -31,6 +31,7 @@ import { addRule, removeRule } from "./rules";
 import { askSaad } from "./ask-tool";
 import { askQuestion, resolveQuestion } from "./questions";
 import { listOrchestratorPeers, messageOrchestrator } from "./cross";
+import { sweepArm, sweepDryRun } from "./sweep-arm";
 import { PAUSED_REFUSAL } from "./pause";
 import { readSession } from "./read";
 import { reviewTarget, signOffTarget } from "./external-gates";
@@ -216,6 +217,12 @@ export async function runTool(
       const a = p(tool, raw);
       return moveTaskTo(w, a.task, a.machine);
     }
+    case "sweep_dry_run":
+      return sweepDryRun(p(tool, raw).machine);
+    case "sweep_arm": {
+      const a = p(tool, raw);
+      return sweepArm(w, a.machine, a.on, a.reason);
+    }
     case "stop":
       return stop(w, p(tool, raw).session);
     case "done":
@@ -265,8 +272,10 @@ export async function runTool(
       const a = p(tool, raw);
       return reviewTarget(w, a.target, { fresh: a.fresh });
     }
-    case "sign_off":
-      return signOffTarget(w, p(tool, raw).task);
+    case "sign_off": {
+      const a = p(tool, raw);
+      return signOffTarget(w, a.task, { direct: a.direct, reason: a.reason });
+    }
     case "arm":
       return arm(w, p(tool, raw).task);
     case "disarm":

package/lib/orchestrator/shell-guard.ts

@@ -229,6 +229,8 @@ function aosRefusal(args: string[]): string | null {
     resurrect: T.resurrect,
     stop: T.stop,
   };
+  if (sub === "sweep" && args.includes("--arm"))
+    return `Refused: \`aos sweep --arm\` turns on removing files and databases, which is Saad's call: Health, Clean-up, Turn on. When he has said to, use ${T.sweep_arm} (after ${T.sweep_dry_run}). \`--dry-run\` and \`--disarm\` are fine.`;
   if (sub && tool[sub])
     return `Refused: \`aos ${sub}\` isn't for you; use ${tool[sub]}, which is scoped to this workspace and held by Pause.`;
   return null;
@@ -615,3 +617,25 @@ export async function shellRefusal(
   }
   return null;
 }
+
+// The one thing full access still flags: a command that looks like it stops
+// or restarts AgentOS or its tmux, which ends every session it runs, this one
+// included. A warning, never a refusal; null for anything else.
+export async function shellWarning(
+  command: unknown,
+  ctx: ShellContext
+): Promise<string | null> {
+  if (typeof command !== "string") return null;
+  const parsed = parseShell(command);
+  if (typeof parsed === "string") return null;
+  for (const cmd of parsed) {
+    const invs = invocations(cmd);
+    if (typeof invs === "string") continue;
+    for (const inv of invs) {
+      const why = await stopRefusal(inv, ctx).catch(() => null);
+      if (why)
+        return `Warning: ${why.replace(/^Refused: /, "")} It will run anyway.`;
+    }
+  }
+  return null;
+}

package/lib/orchestrator/signoff.test-helpers.ts

@@ -6,6 +6,7 @@ import { beforeAll, beforeEach, expect, vi } from "vitest";
 import type { TaskPR } from "@/lib/tasks/state";
 import type { ClaudeRun } from "./claude-cli";
 import type { SessionFacts } from "./facts";
+import { tempDir } from "@/lib/test-temp";
 
 // Shared fixtures for the signoff*.test.ts files: a real repository with a
 // local bare remote, gh faked around it. Import this before anything it mocks.
@@ -162,7 +163,7 @@ export const askUp = async (
 export const POLL = { timeout: 20000, interval: 20 };
 
 beforeAll(() => {
-  const home = fs.mkdtempSync(path.join(os.tmpdir(), "aos-orch-signoff-"));
+  const home = tempDir("aos-orch-signoff-");
   vi.spyOn(os, "homedir").mockReturnValue(home);
 });
 beforeEach(() => {
@@ -212,7 +213,7 @@ export function setup(
   } = {}
 ) {
   setMergeApprovals(opts.approvals ?? false);
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), "aos-orch-repo-"));
+  const root = tempDir("aos-orch-repo-");
   const remote = path.join(root, "remote.git");
   const repo = path.join(root, "repo");
   git(root, "init", "-q", "--bare", "-b", "main", remote);

package/lib/orchestrator/sweep-arm.ts

@@ -0,0 +1,180 @@
+/**
+ * The orchestrator's way to turn the full disk clean-up on or off, for this
+ * machine or a linked one. Turning it on is Saad's call, so the tool says it's
+ * for when he has said to, wants the latest dry run of that machine from the
+ * last hour (what it would remove is what he agreed to), and logs who and
+ * the dry run's totals. A linked machine is armed over ssh to its own
+ * loopback, where its AgentOS trusts the caller: its arm endpoint refuses a
+ * device token on purpose.
+ */
+
+import { getHost, hostExec, hostIdNamed, isRemoteHost } from "../hosts";
+import { remotePort } from "../hosts/link";
+import {
+  cleanRemoteText,
+  hostApi,
+  requireHostLink,
+  type HostLink,
+} from "../hosts/remote-api";
+import { fromSqliteTime } from "../session-meta";
+import { setReaperArmed } from "../worktree-sweep/settings";
+import { sweepNow } from "../worktree-sweep/start";
+import { sweepState, type SweepState } from "../worktree-sweep/state";
+import type { SweepRun } from "../worktree-sweep/types";
+import { addNote } from "./notes";
+import { PAUSED_REFUSAL } from "./pause";
+import { getWorkspace } from "../workspaces";
+
+export const DRY_RUN_FRESH_MS = 60 * 60 * 1000;
+
+const TOOL_DRY = "sweep_dry_run";
+const GB = (b: number) => (b / 1024 ** 3).toFixed(2) + " GB";
+
+type Verdict = { ok: true; run: SweepRun } | { ok: false; why: string };
+
+// The newest dry run decides: an older fresh one doesn't stand in for it.
+export function dryRunVerdict(
+  runs: SweepRun[],
+  where: string,
+  now = Date.now()
+): Verdict {
+  const next = `Run ${TOOL_DRY} for ${where} first (it takes a few minutes), then call sweep_arm again.`;
+  const run = runs.find((r) => r.dryRun);
+  if (!run) return { ok: false, why: `${where} has no dry run. ${next}` };
+  if (!run.finishedAt)
+    return {
+      ok: false,
+      why: `The dry run on ${where} is still going. Wait for it, then call sweep_arm again.`,
+    };
+  if (run.error)
+    return {
+      ok: false,
+      why: `The latest dry run on ${where} failed (${run.error}). ${next}`,
+    };
+  const age = now - fromSqliteTime(run.finishedAt).getTime();
+  if (age > DRY_RUN_FRESH_MS)
+    return {
+      ok: false,
+      why: `The latest dry run on ${where} is ${Math.round(age / 60000)} minutes old; it must be from the last hour. ${next}`,
+    };
+  return { ok: true, run };
+}
+
+export function totalsLine(run: SweepRun, now = Date.now()): string {
+  const d = run.details;
+  const mins = run.finishedAt
+    ? Math.max(
+        0,
+        Math.round((now - fromSqliteTime(run.finishedAt).getTime()) / 60000)
+      )
+    : 0;
+  return (
+    `dry run #${run.id} (${mins} min ago): would remove ${run.removed} (${GB(run.freedBytes)}), ` +
+    `${d?.pendingTotal?.count ?? 0} (${GB(d?.pendingTotal?.bytes ?? 0)}) waiting for the full clean-up, ${run.skipped} kept` +
+    (d?.report ? `; list: ${cleanRemoteText(d.report)}` : "")
+  );
+}
+
+interface Machine {
+  hostId: string;
+  name: string;
+  link: HostLink | null;
+}
+
+function machineOf(ref: string): Machine {
+  const hostId = hostIdNamed(ref);
+  if (!isRemoteHost(hostId))
+    return { hostId, name: "this machine", link: null };
+  return {
+    hostId,
+    name: getHost(hostId)?.name ?? ref,
+    link: requireHostLink(hostId),
+  };
+}
+
+// Another machine's numbers, read defensively.
+function clean(state: SweepState): SweepState {
+  const num = (n: unknown) => (Number.isFinite(Number(n)) ? Number(n) : 0);
+  return {
+    ...state,
+    armed: state.armed === true,
+    runs: (Array.isArray(state.runs) ? state.runs : []).map((r) => ({
+      ...r,
+      id: num(r.id),
+      dryRun: r.dryRun === true,
+      removed: num(r.removed),
+      freedBytes: num(r.freedBytes),
+      skipped: num(r.skipped),
+      error: r.error ? cleanRemoteText(r.error) : null,
+    })),
+  };
+}
+
+const readState = async (m: Machine): Promise<SweepState> =>
+  m.link
+    ? clean(await hostApi<SweepState>(m.link, "/api/worktree-sweep"))
+    : sweepState();
+
+async function setArmed(m: Machine, armed: boolean): Promise<void> {
+  if (!m.link) return setReaperArmed(armed);
+  if (!armed) {
+    await hostApi(m.link, "/api/worktree-sweep", {
+      method: "PUT",
+      body: { armed: false },
+    });
+    return;
+  }
+  const port = remotePort(m.link.url);
+  await hostExec(
+    m.hostId,
+    `curl -fsS -m 10 -X PUT -H 'Content-Type: application/json' -d '{"armed":true}' http://127.0.0.1:${port}/api/worktree-sweep`,
+    20000
+  ).catch((err) => {
+    throw new Error(
+      `Couldn't turn it on for ${m.name}: ${cleanRemoteText(err instanceof Error ? err.message : err)}`
+    );
+  });
+  if (!(await readState(m)).armed)
+    throw new Error(`${m.name} did not turn the full clean-up on`);
+}
+
+export async function sweepArm(
+  workspaceId: string,
+  machine: string,
+  on: boolean,
+  reason: string
+): Promise<string> {
+  const m = machineOf(machine);
+  const state = await readState(m);
+  const latest = state.runs.find((r) => r.dryRun && r.finishedAt && !r.error);
+  if (state.armed === on)
+    return `The full clean-up is already ${on ? "on" : "off"} for ${m.name}.`;
+  if (on) {
+    // Turning it off only makes things safer, so Pause doesn't hold it.
+    if (getWorkspace(workspaceId)?.orch_paused_at)
+      throw new Error(PAUSED_REFUSAL);
+    const verdict = dryRunVerdict(state.runs, m.name);
+    if (!verdict.ok) throw new Error(verdict.why);
+  }
+  await setArmed(m, on);
+  const totals = latest ? ` Latest ${totalsLine(latest)}.` : "";
+  const line = `Orchestrator turned the full disk clean-up ${on ? "on" : "off"} for ${m.name}: ${reason}.${totals}`;
+  addNote(workspaceId, line);
+  return line;
+}
+
+export async function sweepDryRun(machine: string): Promise<string> {
+  const m = machineOf(machine);
+  const started = `Dry run started on ${m.name}; it takes a few minutes and removes nothing. When Saad has said to turn the full clean-up on, call sweep_arm: it reads this run.`;
+  if (m.link) {
+    await hostApi(m.link, "/api/worktree-sweep/run", {
+      body: { dryRun: true },
+    });
+    return started;
+  }
+  await new Promise<void>((resolve, reject) => {
+    sweepNow(true).then(() => resolve(), reject);
+    setTimeout(resolve, 250);
+  });
+  return started;
+}

package/lib/orchestrator/tool-names.ts

@@ -29,6 +29,8 @@ export const TOOL_NAMES = {
   plan_pieces: name("plan_pieces"),
   drop: name("drop"),
   move: name("move"),
+  sweep_dry_run: name("sweep_dry_run"),
+  sweep_arm: name("sweep_arm"),
   set_priority: name("set_priority"),
   start_now: name("start_now"),
   pause_task: name("pause_task"),
@@ -67,7 +69,8 @@ export const TOOL_NAMES = {
 // task worktree other than its own quick changes, writing AgentOS's state,
 // stopping AgentOS or its tmux, and reading secrets. That catches honest
 // mistakes, not a determined bypass. Its file writes are checked the same
-// way, against a longer list (write-guard.ts).
+// way, against a longer list (write-guard.ts). All of that applies only with
+// the workspace's Orchestrator full access off (full-access.ts).
 export const ORCHESTRATOR_PERMISSIONS: {
   permissionMode: PermissionMode;
   allowedTools: string[];

package/lib/orchestrator/tool-schemas.ts

@@ -21,6 +21,13 @@ const view = z
     "How its agent runs: chat (the default), or terminal only when the job needs a TUI (an interactive program, a full-screen tool)"
   );
 
+const sweepMachine = z
+  .string()
+  .trim()
+  .min(1)
+  .max(200)
+  .describe('A linked machine\'s name (see Machines), or "here" for this one');
+
 const modelRef = z
   .string()
   .trim()
@@ -268,6 +275,17 @@ export const TOOL_SHAPES = {
         'A linked machine\'s name (see Machines), or "here" to bring the task back'
       ),
   },
+  sweep_dry_run: { machine: sweepMachine },
+  sweep_arm: {
+    machine: sweepMachine,
+    on: z.boolean().describe("true turns the full clean-up on, false off"),
+    reason: z
+      .string()
+      .trim()
+      .min(1)
+      .max(500)
+      .describe("What Saad said, and when; it goes in the decision log"),
+  },
   set_priority: {
     task: ref("A queued or running task: name, project/name or id"),
     priority: z.enum(PRIORITIES),
@@ -409,7 +427,21 @@ export const TOOL_SHAPES = {
       .optional()
       .describe("Run it again even if this commit has a verdict"),
   },
-  sign_off: { task },
+  sign_off: {
+    task,
+    direct: z
+      .boolean()
+      .optional()
+      .describe(
+        "Merge now at the PR's head without the gates; needs Orchestrator full access and a reason"
+      ),
+    reason: z
+      .string()
+      .trim()
+      .max(300)
+      .optional()
+      .describe("Why the gates are skipped (required with direct)"),
+  },
   arm: { task },
   disarm: { task },
   ask_saad: {

package/lib/orchestrator/tools.ts

@@ -132,7 +132,7 @@ const DESCRIPTIONS: Record<ToolName, string> = {
   start_session:
     'Start an agent session in a project with a prompt, for work that isn\'t a PR task. It runs on the implementation model unless you give model (one "provider/model"; Opus only when the work needs deep reasoning), 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).",
+    "Make a change yourself (without full access, a small low-risk one: a typo, a config value, a one-file fix): cuts a worktree and branch from the project's default branch and returns its path. Its dependencies install in the background (a note says when). You may write there (Write, Edit) and, with Orchestrator full access, run any git there; without it, only `git -C <path> ...` status, diff, add, rm, mv, restore, reset, log, show, and nowhere else in a project. Without full access, 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:
@@ -145,6 +145,10 @@ const DESCRIPTIONS: Record<ToolName, string> = {
     "A task whose plan split into pieces: each piece, its repo, what it waits on and its state. With merge or drop (position numbers) it edits the pieces still waiting: a merged piece's slice goes to the piece before it, a dropped one is left out and anything waiting on it is held. It can't add pieces or change reasons.",
   drop: "Reject a task: close its PR and remove its worktree. A task still waiting in the queue is removed by its id. Logged with the reason.",
   move: 'Carry a running task to a linked machine, or back with "here": for heavy test or build work. It keeps its branch, conversation and plan; the gates, events, read, send, stop, done and drop work the same wherever it runs, and the machine it lands on can\'t merge it. Takes a few minutes and runs in the background; an event says when it lands. Refused while paused, for a task waiting on Saad (an escalation or open ask), and for card and stacked tasks.',
+  sweep_dry_run:
+    "Start a dry run of the disk clean-up on this machine or a linked one: it lists what the full clean-up would remove and removes nothing. Takes a few minutes; sweep_arm reads it.",
+  sweep_arm:
+    "Turn the full disk clean-up (test leftovers, stale task databases, spares, temp folders, build caches) on or off for this machine or a linked one. Only for when Saad has said to turn it on: put what he said in reason. Turning it on is refused unless that machine's latest dry run finished in the last hour (run sweep_dry_run first, and read its totals). Off is always allowed. Logged in the decision log with the dry run's totals.",
   set_priority:
     "Change the priority of a queued task (it re-ranks the line at once) or a running one (it only matters if it is paused and waits to resume). urgent starts first even on a busy machine; background starts last.",
   start_now:
@@ -183,7 +187,7 @@ const DESCRIPTIONS: Record<ToolName, string> = {
   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:
-    "Merge a PR, with its project's merge method, through the gates: CI green and settled, a passing review of that commit, nothing blocked, in scope, stack parent merged. Takes a task, or any open PR in a workspace repository by #N, owner/repo#N or URL (an external PR). Refuses with the failing gate, or a repository outside the workspace.",
+    "Merge a PR, with its project's merge method, through the gates: CI green and settled, a passing review of that commit, nothing blocked, in scope, stack parent merged. Takes a task, or any open PR in a workspace repository by #N, owner/repo#N or URL (an external PR). Refuses with the failing gate, or a repository outside the workspace. With direct true (and a reason) it merges now at the PR's head without the gates; only with Orchestrator full access, and not while paused or while the task waits on Saad.",
   arm: "Arm a task's PR to merge: AgentOS merges it, through the same gates as sign_off, the moment they all pass at its head, and tells you with one event. A gate failure comes as one event and it stays armed for the fix; one that goes to Saad disarms it. Survives restarts. Use it instead of calling sign_off until it passes.",
   disarm:
     "Disarm a task armed to merge: it merges only through sign_off again.",