@saadnvd1/agent-os 0.3.537 → 0.3.539

package/README.md

@@ -122,10 +122,12 @@ conversation in **Messages** and can join in. [More](#agent-network)
 
 ![A session in terminal view, with the agent asking before it runs a command](screenshots/terminal.png)
 
-**Guides:** step-by-step how-tos are in [`docs/guides/`](docs/guides/), starting with [using AgentOS from your phone](docs/guides/phone.md).
+**Guides:** step-by-step how-tos are in [`docs/guides/`](docs/guides/), starting with [installing AgentOS](docs/guides/install.md) and [using it from your phone](docs/guides/phone.md).
 
 ## Install
 
+The [install guide](docs/guides/install.md) walks through this step by step.
+
 You need Node.js 20+, tmux, and at least one agent CLI:
 [Claude Code](https://github.com/anthropics/claude-code),
 [Codex](https://github.com/openai/codex),
@@ -1590,8 +1592,11 @@ approved`). An approval covers that one item only: a held task's approval
   pass, by giving `ask_saad` the task and its head sha: the ask is pinned to
   that commit, opens with what AgentOS knows about it (files changed,
   sensitive files, the review's verdict) and links the PR, and your approval
-  lets `sign_off` merge it once, at that commit, with a code review of it in
-  the PR body. It never rewrites an ask the gates raised.
+  lets `sign_off` merge it once, at that commit. It never rewrites an ask the
+  gates raised. An approved merge (either kind, and an armed task's) needs no
+  review or other gate of that commit: only an AI-attributed PR body, failing
+  CI (running CI waits), a head that moved off the commit, and on the
+  orchestrator's own ask a stack parent not merged yet, still stop it.
   An ask closes itself when its task is merged or dropped, or the brakes
   lift. At most 10 are open per workspace, titles that say the same thing
   fold into one, a declined subject isn't asked again for 6 hours, and a

package/lib/orchestrator/armed.ts

@@ -8,7 +8,8 @@
  * The orchestrator hears one event: merged, or a failure. A failure is
  * counted against the task once per head, as sign_off would count it, and
  * reported once; the task stays armed for its fix. One that goes to Saad
- * disarms it, since only he merges it from then on. The flag is in the
+ * disarms it, since only he merges it from then on, or approves its head
+ * for it to merge on that approval. The flag is in the
  * database, so it survives a restart.
  */
 
@@ -85,17 +86,19 @@ export function arm(workspaceId: string, ref: string): string {
 }
 
 // Arms a task, or says why it can't be: only a running task, in a
-// workspace whose orchestrator hears how it went, that isn't with Saad.
+// workspace whose orchestrator hears how it went, that isn't with Saad
+// (or that he approved a commit of: it merges on that, at that commit only).
 export function armTask(task: Session): void {
   if (task.task_status !== "running")
     throw new Error(`${task.name} is already ${task.task_status}`);
-  const held = holdingEscalations(task.id);
+  const w = armingWorkspace(task);
+  const approved = !!w && !!latestApproval(w, workSubject(task.id))?.sha;
+  const held = approved ? [] : holdingEscalations(task.id);
   if (held.length)
     throw new Error(
       `${task.name} is with Saad (${held.map((h) => h.gate).join(", ")}); only he merges it`
     );
-  const w = armingWorkspace(task);
-  if (w && openBySubject(w, workSubject(task.id)))
+  if (w && !approved && openBySubject(w, workSubject(task.id)))
     throw new Error(
       `${task.name} has an open ask with Saad; it merges on his answer`
     );
@@ -209,9 +212,16 @@ async function mergeOne(
     return;
   }
   // With Saad, on a gate or on a question about it: he decides, so it
-  // doesn't merge by itself meanwhile.
-  const held = holdingEscalations(task.id).map((h) => h.gate);
-  if (!held.length && openBySubject(workspaceId, workSubject(task.id)))
+  // doesn't merge by itself meanwhile, unless he approved this head.
+  const approved =
+    !!pr.head &&
+    latestApproval(workspaceId, workSubject(task.id))?.sha === pr.head;
+  const held = approved ? [] : holdingEscalations(task.id).map((h) => h.gate);
+  if (
+    !approved &&
+    !held.length &&
+    openBySubject(workspaceId, workSubject(task.id))
+  )
     held.push("an open ask");
   if (held.length) {
     setArmed(task.id, false);

package/lib/orchestrator/ask-tool.ts

@@ -122,7 +122,7 @@ export async function askSaad(
   }
   const { ask, created } = raised;
   const once = merge
-    ? ` If he approves, sign_off merges it once, at ${merge.sha.slice(0, 7)} only.`
+    ? ` If he approves, sign_off merges it once, at ${merge.sha.slice(0, 7)} only, without waiting on a review.`
     : "";
   if (!created)
     return `Already on Saad's list as ask ${ask.id}; updated it.${once} Carry on with everything else.`;

package/lib/orchestrator/brief.ts

@@ -86,11 +86,11 @@ ${brakesEnabled() ? BRAKES_ON : BRAKES_OFF}
 - Credentials and account security.
 - Choosing what gets built when it's a product call he hasn't made.
 
-When one of these comes up, park it with \`ask_saad\` (kind: the hard line it crosses) and carry on with everything else. Use it too for a decision that's his (kind: decision). Escalated gates and brakes become asks on their own; don't ask again for those. To ask whether to merge a PR the gates won't pass, give \`ask_saad\` the task and the PR's head sha: if he approves, \`sign_off\` merges it once, at that commit only.
+When one of these comes up, park it with \`ask_saad\` (kind: the hard line it crosses) and carry on with everything else. Use it too for a decision that's his (kind: decision). Escalated gates and brakes become asks on their own; don't ask again for those. To ask whether to merge a PR the gates won't pass, give \`ask_saad\` the task and the PR's head sha: if he approves, \`sign_off\` merges it once, at that commit only, without the review gates.
 
 ## Asks and pause
 
-Saad answers an ask on his list, and the answer reaches you as an event: \`ask "<title>": approved\`, \`declined\`, or \`reply: <text>\`. Act on it. An approval covers that one item only, never standing permission: the next item like it is a new ask. Approving a held task lets \`sign_off\` merge it once, at the commit he approved; approving a brake lets one start through, once.
+Saad answers an ask on his list, and the answer reaches you as an event: \`ask "<title>": approved\`, \`declined\`, or \`reply: <text>\`. Act on it. An approval covers that one item only, never standing permission: the next item like it is a new ask. Approving a merge (a held task's or your own ask's) lets \`sign_off\`, or an armed task, merge it once at the commit he approved, with no review, scope or other gate in the way: only an AI-attributed PR body, failing CI (running CI is a wait), an unmerged stack parent on your own ask, or a head that moved off that commit still stop it; approving a brake lets one start through, once.
 
 Anything you need from Saad in chat (a question, a choice, a confirmation) goes through \`question\` in the same turn you ask it, and you still write the question plainly in your reply. It stays pinned on his Needs-you strip until it is resolved: when he answers (in chat, or with the strip's Reply) or it stops mattering, call \`resolve_question\`. Don't leave one open once he has answered. \`ask_saad\` is for hard lines and calls that need Approve or Decline; \`question\` is for everything conversational. Don't open a question for something that is already an ask. Updates AgentOS sends you fold into one-line rows in his chat, so a question buried in a long reply to an event is easy to miss: that is what \`question\` is for.
 

package/lib/orchestrator/gates.ts

@@ -65,7 +65,18 @@ export interface GateInput {
 
 const short = (sha: string) => sha.slice(0, 7);
 
-function ciGate(i: GateInput): GateOutcome {
+export function ciGate(
+  i: Pick<
+    GateInput,
+    | "sha"
+    | "checks"
+    | "failing"
+    | "settleIn"
+    | "mergeable"
+    | "baseName"
+    | "repoCI"
+  >
+): GateOutcome {
   const gate = "ci";
   const at = short(i.sha);
   if (i.checks === "pending")
@@ -88,7 +99,7 @@ function ciGate(i: GateInput): GateOutcome {
 
 // A head with no checks. Only a repository with no CI at all has nothing to
 // gate on; in one with CI the head is not yet, whatever the reason.
-function noChecks(i: GateInput, at: string): GateOutcome {
+function noChecks(i: Parameters<typeof ciGate>[0], at: string): GateOutcome {
   const gate = "ci";
   const wait = (reason: string): GateOutcome => ({
     gate,

package/lib/orchestrator/held.ts

@@ -1,5 +1,5 @@
 // A task that's with Saad merges only on his approval of its exact head
-// commit, once. A new commit since he approved goes back to him.
+// commit, once (signoff.ts). A new commit since he approved goes back to him.
 
 import { AskRefused, raiseAsk, workSubject } from "./asks";
 import { latestApproval } from "./ask-approvals";
@@ -17,10 +17,8 @@ export function heldVerdict(
   pr: number,
   moved?: string
 ): Verdict {
-  // One the orchestrator raised was judged before this (signoff.ts).
+  // An approval of this head was judged before this (signoff.ts).
   const approval = latestApproval(workspaceId, workSubject(task.id));
-  if (approval?.sha === sha)
-    return { ok: true, sha, pr, approval: approval.id };
   if (approval) {
     const why = `Saad approved ${approval.sha ? short(approval.sha) : "an earlier commit"}, but PR #${pr}'s head is now ${short(sha)}${moved ? ` and ${moved}` : ""}`;
     try {

package/lib/orchestrator/signoff.ts

@@ -25,7 +25,12 @@ import {
   sensitiveFiles,
 } from "./diff";
 import { countFailure, escalate } from "./escalate";
-import { evaluateGates, holdingEscalations, type GateInput } from "./gates";
+import {
+  ciGate,
+  evaluateGates,
+  holdingEscalations,
+  type GateInput,
+} from "./gates";
 import { addNote } from "./notes";
 import { latestApproval, refundApproval, spendApproval } from "./ask-approvals";
 import { workSubject } from "./asks";
@@ -96,7 +101,11 @@ export async function judge(
         restackedOf(task)?.to === sha
       )
     : null;
-  if (quick?.wait)
+  // Saad's approval of this head stands in for that review (gateVerdict).
+  if (
+    quick?.wait &&
+    latestApproval(workspaceId, workSubject(task.id))?.sha !== sha
+  )
     return {
       ok: false,
       wait: true,
@@ -164,13 +173,12 @@ export async function gateVerdict(
   });
   const { pr, sha, repo } = work;
   const held = holdingEscalations(work.id);
-  // Saad approved merging this exact commit. On an ask the orchestrator
-  // raised (ask_saad with its task and sha), held or not, it merges once
-  // whatever the gates say, but only once an independent review of that
-  // commit finished (its findings are his to override, not that it ran) and
-  // its stack parent merged: the orchestrator wrote that ask, and no answer
-  // to it stands in for those. An approval of the gates' own ask on a held
-  // task merges as it always has (heldVerdict).
+  // Saad approved merging this exact commit: held or not, it merges once,
+  // without a review or any other gate approval stands in for. Approval
+  // doesn't cover what's left: an AI-attributed body, failing CI (running
+  // CI is a wait), and, on an ask the orchestrator raised or a task the
+  // gates don't hold, a stack parent not merged yet. On a held task, an
+  // approval of an earlier commit goes back to him (heldVerdict).
   let approval = latestApproval(workspaceId, workSubject(work.id));
   // The head moved since he approved: his approval follows it when the PR's
   // own patch is unchanged (a rebase), else the re-ask says what changed.
@@ -185,19 +193,19 @@ export async function gateVerdict(
     if (carried.approval) approval = carried.approval;
     else moved = carried.note;
   }
-  if (
-    approval?.sha === sha &&
-    (approval.raised_by === "orchestrator" || !held.length)
-  ) {
+  if (approval?.sha === sha) {
     const i = await inputs();
-    const refusal =
-      i.codeReview.refusal ??
-      (i.codeReview.ran ? null : i.codeReview.wait) ??
-      i.stackRefusal;
-    if (refusal)
-      return no(
-        `${work.name} (PR #${pr.number} at ${short(sha)}): Saad approved this commit, but ${refusal}`
-      );
+    const approved = `${work.name} (PR #${pr.number} at ${short(sha)}): Saad approved this commit, but`;
+    const stack =
+      approval.raised_by === "orchestrator" || !held.length
+        ? i.stackRefusal
+        : null;
+    const refusal = i.codeReview.refusal ?? stack;
+    if (refusal) return no(`${approved} ${refusal}`);
+    const ci = ciGate({ sha, ...i, repoCI: await repoCIFor(repo, work, i) });
+    if (ci.state === "fail") return no(`${approved} ${ci.reason}`);
+    if (ci.state === "wait") return no(`${approved} ${ci.reason}`, true);
+    // "escalate" is a repository with no CI: Saad is who that goes to.
     return { ok: true, sha, pr: pr.number, approval: approval.id };
   }
   if (held.length)
@@ -223,14 +231,7 @@ export async function gateVerdict(
 
   const ruled = ruleBreaks(files, await addedLines(repo, base, sha));
   const live = await inputs();
-  // Asked only when it can change the answer: a head with no checks that
-  // isn't settling or conflicting.
-  const repoCI =
-    live.checks === "none" &&
-    live.settleIn === 0 &&
-    live.mergeable !== "CONFLICTING"
-      ? await repoHasCI(repo, base)
-      : undefined;
+  const repoCI = await repoCIFor(repo, base, live);
   const outcomes = evaluateGates({ sha, ruleBreaks: ruled, ...live, repoCI });
   const head = `${work.name} (PR #${pr.number} at ${short(sha)}) can't merge:`;
   const toSaad = outcomes.find((o) => o.state === "escalate");
@@ -253,6 +254,25 @@ export async function gateVerdict(
   return no(`${head}\n${lines.join("\n")}`, !failed.length);
 }
 
+// Asked only when it can change the answer: a head with no checks that
+// isn't settling or conflicting.
+async function repoCIFor(
+  repo: string,
+  base: string | GateWork,
+  i: Pick<GateInput, "checks" | "settleIn" | "mergeable">
+) {
+  if (i.checks !== "none" || i.settleIn !== 0 || i.mergeable === "CONFLICTING")
+    return undefined;
+  if (typeof base !== "string") {
+    try {
+      base = await fetchRefs(repo, base.refs);
+    } catch {
+      return undefined;
+    }
+  }
+  return repoHasCI(repo, base);
+}
+
 export async function signOff(
   workspaceId: string,
   ref: string

package/lib/orchestrator/tools.ts

@@ -116,7 +116,7 @@ const DESCRIPTIONS: Record<ToolName, string> = {
   resolve_question:
     "Clear an open question once Saad has answered it in chat, or it no longer matters.",
   ask_saad:
-    "Park an item on Saad's asks list (a decision, or anything crossing a hard line) and carry on; it never waits. One open ask per title. His answer reaches you as an event. To ask whether to merge a PR the gates refuse, give task and sha (its head): his approval lets sign_off merge it once, at that commit.",
+    "Park an item on Saad's asks list (a decision, or anything crossing a hard line) and carry on; it never waits. One open ask per title. His answer reaches you as an event. To ask whether to merge a PR the gates refuse, give task and sha (its head): his approval lets sign_off merge it once, at that commit, without a review (an AI-attributed body or failing CI still refuses).",
 };
 
 export function orchestratorTools(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saadnvd1/agent-os",
-  "version": "0.3.537",
+  "version": "0.3.539",
   "description": "Self-hosted web UI for managing Claude Code sessions",
   "bin": {
     "agent-os": "scripts/agent-os"