scribeclock 0.2.0 → 0.3.0

package/README.md

@@ -49,7 +49,8 @@ Run `scribeclock --help` for the full list and `scribeclock <command> --help` fo
 | Vault & env | `vault ls\|get\|set\|credential\|rm` · `env pull\|push` · `run -- <command>` |
 | Cloudflare | `cf accounts\|zones\|dns\|dns set\|dns rm\|dns diff\|pages\|deployments\|deploy-status\|workers\|purge\|request` |
 | Team | `team` · `overlap [files…]` (exit 4 on overlap) · `team report` · `handoff [record]` |
-| Git | `branch KEY [--create]` · `commit -m "…"` · `pr KEY` · `changelog --since <tag>` |
+| Git | `branch KEY [--create]` · `commit -m "…"` · `pr KEY [--reviewer …]` · `changelog --since <tag>` |
+| Pull requests | `prs [--mine]` · `pr gate [--all]` (exit 4 while a PR needs you) · `pr wait [N] [--deploy]` · `pr report [N\|URL] [--reviewer …]` |
 | Bug reports | `connect [--env] [--vault] [--create]` · `issues [show\|resolve --release X\|ignore\|reopen\|task\|urgency]` · `analytics [--days N] [--report X] [--csv]` · `ingest settings [--immediate critical --per-hour 2 --every 120]` · `bug "title" [-d …] [--log file] [--stack file]` · `ingest keys\|revoke\|test\|snippets\|forward [provider]` · `health [--days N]` |
 | Ops & agents | `doctor` · `watch tasks [--on-change cmd]` · `serve --stdio` · `mcp-config <client> [--install]` · `ask "…"` |
 | Raw tools | `tools` · `call <tool> [--arg v \| --args '{json}']` · `<tool_name> …` · `refresh` |
@@ -154,8 +155,23 @@ scribeclock hooks status
 With the hooks installed, the agent's session starts with one server call (`scribeclock session`, which
 runs `start_repo_session`: clock, your tasks, who is active, the handoff to resume from, overlaps, inbox),
 every file edit keeps your presence fresh (`scribeclock heartbeat`, debounced, no tokens), every `git push`
-tells teammates' agents to pull, every `git pull` clears the notice, and the session end leaves a handoff.
-Only warnings (a teammate pushed, someone is on the same file, a message) are put in front of the agent.
+tells teammates' agents to pull, every `git pull` clears the notice, every `gh pr create` records the PR and
+notifies its reviewers, and the session end leaves a handoff. Only warnings (a teammate pushed, a pull request
+needs you, someone is on the same file, a message) are put in front of the agent.
+
+### Pull request gate
+
+Like the pull notice, a pull request that needs you stays at the top of your agent's replies
+(`pr_action_required`) until it is handled: a review someone asked of you, changes requested on yours, red CI,
+an approved PR waiting to be merged, or a failed deploy after merge. Reviewers are notified as soon as the PR
+is opened (through the GitHub webhook, or the hook above when `gh pr create` runs).
+
+```bash
+scribeclock pr '#731' --reviewer octocat     # open, notify, attach to the task
+scribeclock prs                              # this repository's PRs and what each needs from you
+scribeclock pr gate || echo "handle your PRs first"   # exit 4 while something blocks
+scribeclock pr wait --deploy                 # block until this branch's PR is merged and deployed
+```
 Commit `.claude/settings.json` / `.cursor/hooks.json` so the whole team gets it.
 
 `scribeclock session` and `scribeclock heartbeat` also work by hand, and `scribeclock serve --stdio` runs

package/dist/commands/agent.js

@@ -17,6 +17,7 @@ import { changedFiles, currentBranch, detectTaskKey, git, gitState, lastCommit,
 import { EXIT } from "../types.js";
 import { fmtDate } from "../util/format.js";
 import { cmd, emit, list, num, str, taskKey } from "./_shared.js";
+import { isGhPrCreate, prUrlFrom, reportNotice, reportPullRequest, reviewersFromCommand } from "./pulls.js";
 export const HOOK_CLIENTS = ["claude-code", "cursor"];
 /** Seconds between two presence reports for the same file set (new files always report). */
 export const HEARTBEAT_MIN_INTERVAL_S = 300;
@@ -44,8 +45,11 @@ export function parseHookEvent(input, client) {
             const path = str(ti.file_path) ?? str(ti.notebook_path);
             return { ...base, kind: "edit", files: path ? [path] : [] };
         }
-        if (name === "PostToolUse" && tool === "Bash")
-            return { ...base, kind: "shell", files: [], command: str(ti.command) ?? "" };
+        if (name === "PostToolUse" && tool === "Bash") {
+            const resp = input.tool_response;
+            const output = typeof resp === "string" ? resp : resp && typeof resp === "object" ? str(resp.stdout) : undefined;
+            return { ...base, kind: "shell", files: [], command: str(ti.command) ?? "", output };
+        }
         return { ...base, kind: "other", files: [] };
     }
     // Cursor
@@ -58,7 +62,7 @@ export function parseHookEvent(input, client) {
         return { ...base, kind: "edit", files: path ? [path] : [] };
     }
     if (name === "afterShellExecution")
-        return { ...base, kind: "shell", files: [], command: str(input.command) ?? "" };
+        return { ...base, kind: "shell", files: [], command: str(input.command) ?? "", output: str(input.output) };
     return { ...base, kind: "other", files: [] };
 }
 export function isGitPush(command) {
@@ -181,6 +185,8 @@ export function presenceNotices(data) {
     const lines = [];
     if (typeof data.git_pull_required === "string")
         lines.push(data.git_pull_required.split(". In your local")[0] + ". Run `git pull --rebase --autostash` before touching files.");
+    if (typeof data.pr_action_required === "string")
+        lines.push(data.pr_action_required);
     const overlaps = Array.isArray(data.overlaps) ? data.overlaps : [];
     for (const o of overlaps.slice(0, 3)) {
         const who = o.is_my_other_session ? "Your other agent session" : String(o.person?.name ?? o.person?.email ?? "A teammate");
@@ -258,7 +264,7 @@ export const sessionCommand = cmd({
             const lines = [
                 `ScribeClock session started (${repo}). Hooks are installed: presence heartbeats, push notices and pull checks are automatic — do not call report_repo_activity, announce_push or check_repo_overlap yourself; still use report_task_progress on the person's task and record_handoff when stopping.`,
                 String(data.brief ?? ""),
-                ...presenceNotices({ git_pull_required: data.git_pull_required, inbox: data.inbox }),
+                ...presenceNotices({ git_pull_required: data.git_pull_required, pr_action_required: data.pr_action_required, inbox: data.inbox }),
             ].filter(Boolean);
             ctx.out.stdout.write(JSON.stringify(hookContext(client, event?.eventName || "SessionStart", lines.join("\n"))) + "\n");
             return EXIT.OK;
@@ -281,6 +287,8 @@ function renderSession(ctx, data, repo) {
         ctx.out.warn(String(w));
     if (typeof data.git_pull_required === "string")
         ctx.out.warn(String(data.git_pull_required).split(". In your local")[0] + ".");
+    if (typeof data.pr_action_required === "string")
+        ctx.out.warn(String(data.pr_action_required));
 }
 // ---------------------------------------------------------------------------
 // scribeclock heartbeat
@@ -289,8 +297,8 @@ export const heartbeatCommand = cmd({
     path: "heartbeat",
     group: "Automation & agents",
     summary: "Report presence from the local git state, debounced; as a hook it also announces pushes and records pulls.",
-    description: "Sends report_repo_activity with the branch, the files touched recently and the git state, but only when new files appear or --min-interval seconds passed (so an editor hook can call it on every edit for free). With --hook claude-code|cursor it reads the hook event from stdin: file edits become presence, a `git push` becomes announce_push, a `git pull` clears the pull notice, and the session end leaves a handoff. Only warnings (a teammate's push, an overlap, a message) are printed back into the agent's context; nothing else costs tokens.",
-    tool: ["report_repo_activity", "announce_push", "record_handoff"],
+    description: "Sends report_repo_activity with the branch, the files touched recently and the git state, but only when new files appear or --min-interval seconds passed (so an editor hook can call it on every edit for free). With --hook claude-code|cursor it reads the hook event from stdin: file edits become presence, a `git push` becomes announce_push, a `git pull` clears the pull notice, `gh pr create` / `gh pr ready` becomes report_pull_request (reviewers notified), and the session end leaves a handoff. Only warnings (a teammate's push, a pull request that needs you, an overlap, a message) are printed back into the agent's context; nothing else costs tokens.",
+    tool: ["report_repo_activity", "announce_push", "record_handoff", "report_pull_request"],
     positionals: [{ name: "files", variadic: true, description: "Files touched (default: from the hook event, else uncommitted changes)." }],
     flags: [
         REPO_FLAG,
@@ -307,7 +315,7 @@ export const heartbeatCommand = cmd({
         const event = client ? parseHookEvent(await readStdinJson(ctx), client) : null;
         if (event && event.kind === "other")
             return EXIT.OK;
-        if (event && event.kind === "shell" && !isGitPush(event.command) && !isGitPull(event.command))
+        if (event && event.kind === "shell" && !isGitPush(event.command) && !isGitPull(event.command) && !isGhPrCreate(event.command))
             return EXIT.OK;
         const cwd = event?.cwd ?? ctx.cwd;
         const repo = str(inv.flags.repo) ?? repoRef(cwd);
@@ -363,6 +371,16 @@ export const heartbeatCommand = cmd({
                 return EXIT.OK;
             });
         }
+        if (event?.kind === "shell" && isGhPrCreate(event.command)) {
+            return guard(async () => {
+                const data = await reportPullRequest(ctx, { cwd, repo, url: prUrlFrom(event.output), reviewers: reviewersFromCommand(event.command) });
+                state.last_error = null;
+                writeState(path, state);
+                if (client && data)
+                    ctx.out.stdout.write(JSON.stringify(hookContext(client, event.eventName, `ScribeClock: ${reportNotice(data)}`)) + "\n");
+                return EXIT.OK;
+            });
+        }
         if (event?.kind === "shell" && isGitPull(event.command)) {
             return guard(async () => {
                 await ctx.call("report_repo_activity", { repo, branch, pulled: true, git: gitState(cwd), session_key: sessionKey, client_name: clientLabel(client) });

package/dist/commands/gitflow.js

@@ -4,6 +4,7 @@ import { changedFiles, currentBranch, detectTaskKey, git, gitState, githubSlug,
 import { EXIT } from "../types.js";
 import { fmtDate, parseWhen, slugify } from "../util/format.js";
 import { PROJECT_FLAG, bool, cmd, emit, list, personName, projectIdArg, str, taskKey } from "./_shared.js";
+import { reportNotice, reportPullRequest } from "./pulls.js";
 /** feat/123-short-title — the prefix comes from .scribeclock.json → branch_prefix (default feat). */
 export function branchNameFor(ctx, task, prefix) {
     const p = prefix ?? ctx.repo.config.branch_prefix ?? "feat";
@@ -105,12 +106,13 @@ export const commitCommand = cmd({
 export const prCommand = cmd({
     path: "pr",
     group: "Git",
-    summary: "Open a GitHub pull request for a task (title + task link + summary) and attach it to the task as evidence.",
+    summary: "Open a GitHub pull request for a task, notify its reviewers through ScribeClock, and attach it to the task as evidence.",
     description: "Needs the GitHub CLI (`gh`) and a pushed branch. The PR title is \"#123 Task title\", the body links the ScribeClock task; the PR url is then reported on the task (outcome=progress, pull_request evidence).",
-    tool: ["get_task", "report_task_progress"],
+    tool: ["get_task", "report_task_progress", "report_pull_request"],
     positionals: [{ name: "task", description: "Task key (default: detected from git)." }],
     flags: [
         { name: "base", alias: "B", type: "string", description: "Base branch (default: the repository default)." },
+        { name: "reviewer", type: "array", description: "Reviewers (GitHub logins; emails or member names are notified on ScribeClock only). Each is told to review before new work." },
         { name: "draft", type: "boolean", description: "Open as a draft." },
         { name: "body", type: "string", description: "Extra body text (@file reads a file)." },
         { name: "no-report", type: "boolean", description: "Do not post the PR on the task." },
@@ -134,6 +136,10 @@ export const prCommand = cmd({
             args.push("--base", String(inv.flags.base));
         if (inv.flags.draft)
             args.push("--draft");
+        const reviewers = list(inv.flags.reviewer) ?? [];
+        const ghReviewers = reviewers.filter((r) => /^@?[A-Za-z0-9][A-Za-z0-9-]{0,38}$/.test(r)).map((r) => r.replace(/^@/, ""));
+        if (ghReviewers.length)
+            args.push("--reviewer", ghReviewers.join(","));
         if (ctx.flags.dryRun) {
             ctx.out.log(`${ctx.out.dim("dry run →")} gh ${args.map((a) => (a.includes(" ") || a.includes("\n") ? JSON.stringify(a.slice(0, 60)) : a)).join(" ")}`);
             return EXIT.OK;
@@ -143,10 +149,16 @@ export const prCommand = cmd({
             throw new CliError(`gh pr create failed: ${(r.stderr || r.stdout).trim()}`, { id: "gh_failed", hint: "Push the branch first (git push -u origin HEAD) and make sure gh is logged in." });
         const url = (r.stdout.trim().split("\n").pop() ?? "").trim();
         ctx.out.info(`${ctx.out.green("✓")} ${url}`);
+        const repo = repoRef(ctx.cwd);
+        const gate = repo ? await reportPullRequest(ctx, { cwd: ctx.cwd, repo, url, reviewers }).catch((err) => ({ ok: false, message: err instanceof Error ? err.message : String(err) })) : null;
+        if (gate && gate.ok !== false)
+            ctx.out.info(reportNotice(gate));
+        else if (gate)
+            ctx.out.warn(`Reviewers not notified on ScribeClock: ${String(gate.message ?? "error")} (scribeclock pr report)`);
         if (inv.flags["no-report"])
-            return emit(ctx, { ok: true, url, reported: false }, () => undefined);
+            return emit(ctx, { ok: true, url, reported: false, pull_request: gate }, () => undefined);
         const report = await ctx.call("report_task_progress", { task_id: key, outcome: "progress", summary: `Opened pull request ${url}`, evidence: [{ kind: "pull_request", title, url }], repo: repoRef(ctx.cwd) ?? undefined, branch, git: gitState(ctx.cwd) });
-        return emit(ctx, { ok: true, url, reported: true, report }, () => ctx.out.log(`${ctx.out.green("✓")} Pull request attached to ${String(t.key ?? key)}.`));
+        return emit(ctx, { ok: true, url, reported: true, report, pull_request: gate }, () => ctx.out.log(`${ctx.out.green("✓")} Pull request attached to ${String(t.key ?? key)}.`));
     },
 });
 export const changelogCommand = cmd({

package/dist/commands/index.js

@@ -12,6 +12,7 @@ import { CF_COMMANDS } from "./cf.js";
 import { TEAM_COMMANDS } from "./team.js";
 import { WORKFLOW_COMMANDS } from "./workflow.js";
 import { GITFLOW_COMMANDS } from "./gitflow.js";
+import { PULL_COMMANDS } from "./pulls.js";
 import { OPS_COMMANDS } from "./ops.js";
 import { AUTOMATION_COMMANDS } from "./automation.js";
 import { INGEST_COMMANDS } from "./ingest.js";
@@ -24,6 +25,7 @@ export function buildRegistry() {
     registry.add(...CLOCK_COMMANDS);
     registry.add(...TASK_COMMANDS);
     registry.add(...GITFLOW_COMMANDS);
+    registry.add(...PULL_COMMANDS);
     registry.add(...INGEST_COMMANDS);
     registry.add(...PROJECT_COMMANDS);
     registry.add(...MEETING_COMMANDS);

package/dist/commands/pulls.js

@@ -0,0 +1,279 @@
+/**
+ * Pull request gate: `prs`, `pr gate`, `pr wait`, `pr report`.
+ *
+ * Like the push notice (git_pull_required), the server keeps every pull request that needs a person — a review
+ * asked of them, changes requested on theirs, red CI, approved and ready to merge, a failed deploy — and puts it
+ * at the top of their agent's replies (pr_action_required) until it is resolved. These commands read and feed
+ * that gate from a terminal or a script: `pr gate` exits 4 while something blocks, `pr wait` blocks until a PR
+ * is merged (and deployed with --deploy), the way `git pull` blocks until the tree is current.
+ */
+import { spawnSync } from "node:child_process";
+import { CliError, usageError } from "../cli/errors.js";
+import { currentBranch, lastCommit, repoRef } from "../git.js";
+import { EXIT } from "../types.js";
+import { cmd, emit, list, num, str } from "./_shared.js";
+/** A PR number from a flag, positional ("42", "#42") or gh JSON. */
+export function prNumber(v) {
+    const n = typeof v === "number" ? v : typeof v === "string" && /^#?\d+$/.test(v.trim()) ? Number(v.trim().replace(/^#/, "")) : undefined;
+    return n && n > 0 ? n : undefined;
+}
+const PR_URL = /https:\/\/github\.com\/[^\s/]+\/[^\s/]+\/pull\/(\d+)/;
+/** `gh pr create` / `gh pr ready` in a shell command (also after `&&`, `;` or a pipe). */
+export function isGhPrCreate(command) {
+    return Boolean(command && /(^|[;&|\s])gh\s+pr\s+(create|ready)\b/.test(command));
+}
+/** The PR link `gh pr create` printed, if any. */
+export function prUrlFrom(text) {
+    const m = text ? PR_URL.exec(text) : null;
+    return m ? m[0] : null;
+}
+/** Reviewers named on a `gh pr create` command line (`--reviewer a,b`, `-r a`). */
+export function reviewersFromCommand(command) {
+    if (!command)
+        return [];
+    const out = [];
+    const re = /(?:--reviewer|-r)(?:=|\s+)("[^"]*"|'[^']*'|[^\s;&|]+)/g;
+    for (let m = re.exec(command); m; m = re.exec(command))
+        out.push(...m[1].replace(/^["']|["']$/g, "").split(",").map((s) => s.trim()).filter(Boolean));
+    return [...new Set(out)];
+}
+/** `gh pr view` for the current branch (or a number): what report_pull_request needs. Null without gh or a PR. */
+export function ghPrView(cwd, ref, env = process.env) {
+    if (env.SCRIBECLOCK_GH === "0")
+        return null;
+    const args = ["pr", "view", ...(ref ? [ref] : []), "--json", "number,url,title,headRefName,baseRefName,isDraft,headRefOid,reviewRequests"];
+    const r = spawnSync("gh", args, { cwd, encoding: "utf8", timeout: 15_000 });
+    if (r.status !== 0 || !r.stdout)
+        return null;
+    try {
+        return JSON.parse(r.stdout);
+    }
+    catch {
+        return null;
+    }
+}
+/** report_pull_request arguments from `gh pr view` output plus any reviewers named elsewhere. */
+export function reportArgsFromGh(repo, view, extraReviewers = []) {
+    const requested = Array.isArray(view.reviewRequests) ? view.reviewRequests.map((r) => str(r.login)).filter((x) => Boolean(x)) : [];
+    return {
+        repo,
+        url: str(view.url),
+        number: prNumber(view.number),
+        title: str(view.title),
+        head_branch: str(view.headRefName),
+        base_branch: str(view.baseRefName),
+        draft: view.isDraft === true,
+        reviewers: [...new Set([...requested, ...extraReviewers])],
+    };
+}
+/** Reports the PR a hook or `scribeclock pr` just created; returns the server reply (or null when nothing is known). */
+export async function reportPullRequest(ctx, opts) {
+    const view = ghPrView(opts.cwd, opts.url ?? undefined, ctx.env);
+    const args = view
+        ? reportArgsFromGh(opts.repo, view, opts.reviewers)
+        : { repo: opts.repo, url: opts.url ?? undefined, head_branch: currentBranch(opts.cwd) ?? undefined, reviewers: opts.reviewers ?? [] };
+    if (!args.url && !args.number)
+        return null;
+    return ctx.call("report_pull_request", args);
+}
+/** One line for a reviewer's / author's agent after report_pull_request. */
+export function reportNotice(data) {
+    const pr = (data.pull_request ?? {});
+    const notified = Array.isArray(data.notified) ? data.notified.map((p) => String(p.name ?? p.email ?? "a teammate")) : [];
+    const unresolved = Array.isArray(data.unresolved_reviewers) ? data.unresolved_reviewers : [];
+    return `PR #${String(pr.number ?? "?")} recorded on ScribeClock${notified.length ? `; reviewers notified: ${notified.join(", ")}` : data.already_notified ? "; reviewers were already notified" : ""}.` +
+        (unresolved.length ? ` Not found in the organization: ${unresolved.join(", ")}.` : "") +
+        (data.hint ? ` ${String(data.hint)}` : "");
+}
+function gateLine(ctx, g) {
+    const mark = g.blocking ? ctx.out.red("●") : ctx.out.yellow("○");
+    return `${mark} ${ctx.out.bold(`#${String(g.number ?? "?")}`)} ${String(g.status ?? "").replace(/_/g, " ")} ${ctx.out.dim(`(${String(g.role ?? "")}, ${String(g.repo_name ?? g.repo ?? "")})`)}\n    ${String(g.action ?? "")}`;
+}
+function prStatus(pr) {
+    if (pr.state === "merged")
+        return pr.deploy?.state ? `merged · deploy ${pr.deploy.state}` : "merged";
+    if (pr.state === "closed")
+        return "closed";
+    if (pr.draft)
+        return "draft";
+    const parts = [`${pr.approvals ?? 0} approval${pr.approvals === 1 ? "" : "s"}`];
+    if ((pr.reviewers ?? []).some((r) => r.review === "changes_requested"))
+        parts.push("changes requested");
+    if (pr.checks)
+        parts.push(`CI ${pr.checks}`);
+    return parts.join(" · ");
+}
+const REPO_FLAG = { name: "repo", alias: "r", type: "string", placeholder: "<remote|owner/repo>", description: "Repository (default: this folder's git origin)." };
+// ---------------------------------------------------------------------------
+// scribeclock prs
+// ---------------------------------------------------------------------------
+export const prsCommand = cmd({
+    path: "prs",
+    group: "Git",
+    summary: "Pull requests of this repository (or yours everywhere with --mine) and what each needs from you.",
+    tool: "list_pull_requests",
+    flags: [
+        REPO_FLAG,
+        { name: "state", alias: "s", type: "string", choices: ["open", "merged", "closed", "all"], description: "Default open." },
+        { name: "mine", type: "boolean", description: "Only PRs you authored or review, in every repository." },
+    ],
+    examples: ["scribeclock prs", "scribeclock prs --state merged", "scribeclock prs --mine --json"],
+    async run(ctx, inv) {
+        const mine = inv.flags.mine === true;
+        const repo = mine ? str(inv.flags.repo) : str(inv.flags.repo) ?? repoRef(ctx.cwd) ?? undefined;
+        const data = await ctx.call("list_pull_requests", { repo, state: str(inv.flags.state), mine: mine || undefined });
+        return emit(ctx, data, () => {
+            const prs = (data.pull_requests ?? []);
+            if (!prs.length)
+                ctx.out.log(ctx.out.dim("No pull requests recorded. They appear when the GitHub webhook delivers or after report_pull_request."));
+            else
+                ctx.out.table(["#", "Title", "Branch", "Status", "Needs you"], prs.map((p) => [p.number, p.title ?? "", `${p.head_branch ?? "?"} → ${p.base_branch ?? "?"}`, prStatus(p), p.needs_you ? String(p.needs_you.status ?? "").replace(/_/g, " ") : ""]));
+            const gate = (data.gate ?? []);
+            if (gate.length) {
+                ctx.out.log("");
+                for (const g of gate)
+                    ctx.out.log(gateLine(ctx, g));
+            }
+        });
+    },
+});
+// ---------------------------------------------------------------------------
+// scribeclock pr gate
+// ---------------------------------------------------------------------------
+export const prGateCommand = cmd({
+    path: "pr gate",
+    group: "Git",
+    summary: "What pull requests need from you before new work; exits 4 while something blocks (for scripts and pre-work checks).",
+    description: "Blocking: a review asked of you, changes requested on your PR, red CI, an approved PR waiting to be merged, a failed deploy after merge. Waiting on others (review, CI, deploy) is listed but does not block. --all covers every repository you work in.",
+    tool: "list_pull_requests",
+    flags: [REPO_FLAG, { name: "all", type: "boolean", description: "Every repository, not just this one." }],
+    examples: ["scribeclock pr gate", "scribeclock pr gate --all || echo 'resolve your PRs first'"],
+    async run(ctx, inv) {
+        const repo = inv.flags.all ? undefined : str(inv.flags.repo) ?? repoRef(ctx.cwd) ?? undefined;
+        const data = await ctx.call("list_pull_requests", { repo, mine: true });
+        const gate = (data.gate ?? []);
+        const blocking = gate.filter((g) => g.blocking);
+        emit(ctx, { ok: true, repo: repo ?? null, blocking: blocking.length, gate }, () => {
+            if (!gate.length)
+                return ctx.out.log(`${ctx.out.green("✓")} No pull request needs you${repo ? ` in ${repo}` : ""}.`);
+            for (const g of gate)
+                ctx.out.log(gateLine(ctx, g));
+        });
+        return blocking.length ? EXIT.CONFLICT : EXIT.OK;
+    },
+});
+/** Where a PR stands for `pr wait`: done (merged, or deployed with --deploy), failed, or still waiting. */
+export function waitOutcome(pr, wantDeploy) {
+    if (!pr)
+        return "waiting";
+    if (pr.state === "closed")
+        return "closed";
+    if (pr.state !== "merged")
+        return "waiting";
+    if (!wantDeploy)
+        return "merged";
+    if (pr.deploy?.state === "failure")
+        return "deploy_failed";
+    return pr.deploy?.state === "success" ? "deployed" : "waiting";
+}
+export const prWaitCommand = cmd({
+    path: "pr wait",
+    group: "Git",
+    summary: "Block until a pull request is merged (--deploy: and deployed), printing reviews, CI and deploy as they change.",
+    description: "Default PR: the open one for the current branch. Exit 0 when merged (or deployed with --deploy), 1 when it was closed without merging, the deploy failed, or --timeout passed. While waiting, the reviewers have already been told through ScribeClock.",
+    tool: "list_pull_requests",
+    positionals: [{ name: "number", description: "PR number (default: the PR of the current branch)." }],
+    flags: [
+        REPO_FLAG,
+        { name: "deploy", type: "boolean", description: "Also wait for a successful production deploy of the merge." },
+        { name: "interval", type: "number", placeholder: "<seconds>", description: "Seconds between checks (default 30).", default: 30 },
+        { name: "timeout", type: "number", placeholder: "<minutes>", description: "Give up after this many minutes (default 120).", default: 120 },
+        { name: "once", type: "boolean", description: "Check once and exit (scripts, tests)." },
+    ],
+    examples: ["scribeclock pr wait", "scribeclock pr wait 42 --deploy --timeout 60"],
+    async run(ctx, inv) {
+        const repo = str(inv.flags.repo) ?? repoRef(ctx.cwd);
+        if (!repo)
+            throw usageError("Not in a git repository.", "Pass --repo owner/repo.");
+        let number = prNumber(inv.positionals[0]);
+        if (!number) {
+            const branch = currentBranch(ctx.cwd);
+            const data = await ctx.call("list_pull_requests", { repo, state: "open" });
+            const mine = (data.pull_requests ?? []).find((p) => p.head_branch && p.head_branch === branch);
+            number = mine?.number ?? prNumber(ghPrView(ctx.cwd, undefined, ctx.env)?.number);
+            if (!number)
+                throw usageError(`No open pull request for ${branch ?? "this branch"}.`, "Pass the PR number: scribeclock pr wait 42");
+        }
+        const wantDeploy = inv.flags.deploy === true;
+        const interval = Math.max(5, num(inv.flags.interval) ?? 30) * 1000;
+        const deadline = ctx.now().getTime() + Math.max(1, num(inv.flags.timeout) ?? 120) * 60_000;
+        let last = "";
+        let stop = false;
+        const onSignal = () => {
+            stop = true;
+        };
+        process.once("SIGINT", onSignal);
+        try {
+            for (;;) {
+                const data = await ctx.call("list_pull_requests", { repo, number, state: "all" });
+                const pr = (data.pull_requests ?? [])[0];
+                const outcome = waitOutcome(pr, wantDeploy);
+                const line = pr ? `#${number} ${prStatus(pr)}${pr.needs_you?.action ? ` — ${pr.needs_you.action}` : ""}` : `#${number} not recorded yet`;
+                if (line !== last) {
+                    if (ctx.flags.json)
+                        ctx.out.ndjson({ event: "pr_status", at: ctx.now().toISOString(), number, outcome, pull_request: pr ?? null });
+                    else
+                        ctx.out.log(`${ctx.out.dim(ctx.now().toISOString().slice(11, 19))} ${line}`);
+                    last = line;
+                }
+                if (outcome === "merged" || outcome === "deployed") {
+                    if (!ctx.flags.json)
+                        ctx.out.log(`${ctx.out.green("✓")} #${number} ${outcome}. Pull the base branch: git checkout ${pr?.base_branch ?? "main"} && git pull --rebase --autostash`);
+                    return EXIT.OK;
+                }
+                if (outcome === "closed" || outcome === "deploy_failed")
+                    throw new CliError(`#${number} ${outcome === "closed" ? "was closed without merging" : "was merged but its deploy failed"}.`, { id: outcome });
+                if (inv.flags.once || stop)
+                    return EXIT.OK;
+                if (ctx.now().getTime() >= deadline)
+                    throw new CliError(`#${number} is still not ${wantDeploy ? "deployed" : "merged"} after ${num(inv.flags.timeout) ?? 120} minutes.`, { id: "timeout", hint: "Ask the reviewers (scribeclock prs) or wait longer with --timeout." });
+                await new Promise((r) => setTimeout(r, interval));
+            }
+        }
+        finally {
+            process.off("SIGINT", onSignal);
+        }
+    },
+});
+// ---------------------------------------------------------------------------
+// scribeclock pr report
+// ---------------------------------------------------------------------------
+export const prReportCommand = cmd({
+    path: "pr report",
+    group: "Git",
+    summary: "Record a pull request on ScribeClock and notify its reviewers (what the hook does after `gh pr create`).",
+    tool: "report_pull_request",
+    positionals: [{ name: "pr", description: "PR number or URL (default: the PR of the current branch, via gh)." }],
+    flags: [REPO_FLAG, { name: "reviewer", type: "array", description: "Reviewers: GitHub logins, emails or member names (comma-separated or repeated)." }],
+    examples: ["scribeclock pr report", "scribeclock pr report 42 --reviewer octocat,sam@example.com"],
+    async run(ctx, inv) {
+        const repo = str(inv.flags.repo) ?? repoRef(ctx.cwd);
+        if (!repo)
+            throw usageError("Not in a git repository.", "Pass --repo owner/repo.");
+        const ref = inv.positionals[0];
+        const reviewers = list(inv.flags.reviewer) ?? [];
+        const view = ghPrView(ctx.cwd, ref, ctx.env);
+        const args = view
+            ? reportArgsFromGh(repo, view, reviewers)
+            : { repo, url: prUrlFrom(ref) ?? undefined, number: prNumber(ref), head_branch: currentBranch(ctx.cwd) ?? undefined, reviewers };
+        if (!args.url && !args.number)
+            throw usageError("Which pull request?", "Pass its number or URL, or install gh (https://cli.github.com) so the current branch's PR is found.");
+        if (!view && !args.head_branch)
+            args.head_branch = currentBranch(ctx.cwd) ?? undefined;
+        if (!args.title)
+            args.title = lastCommit(ctx.cwd)?.message.split("\n")[0];
+        const data = await ctx.call("report_pull_request", args);
+        return emit(ctx, data, () => ctx.out.log(`${ctx.out.green("✓")} ${reportNotice(data)}`));
+    },
+});
+export const PULL_COMMANDS = [prsCommand, prGateCommand, prWaitCommand, prReportCommand];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scribeclock",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "ScribeClock from the terminal: tasks, time clock, projects, PRDs, meetings, files, vault and Cloudflare — a thin client over the ScribeClock MCP server.",
   "license": "UNLICENSED",
   "author": "Haydar Al-Karar LLC, dba Karar Tech",