scribeclock 0.2.0 → 0.3.1

package/README.md

@@ -30,6 +30,7 @@ Requires Node 20 or newer. No runtime dependencies.
 
 Credentials live in the macOS Keychain or libsecret (`secret-tool`) on Linux; without a usable
 keychain they go to `~/.config/scribeclock/credentials.json` with mode `0600` and a one-time warning.
+Concurrent commands share session refresh safely. Temporary refresh failures preserve the saved login; retry the command when the service is available.
 Tokens are never printed; anything that looks like one is scrubbed from output.
 
 `SCRIBECLOCK_URL` (or `--url`) points the CLI at another server (staging). Logins are kept per server.
@@ -49,7 +50,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` |
@@ -92,6 +94,7 @@ scribeclock start #731                     # claim + clock in against the task +
 scribeclock progress auto "DNS pointed at Pages; waiting for SSL"
 scribeclock commit -m "Point apex at Pages"        # appends (#731) and posts the commit as progress
 scribeclock overlap src/dns.ts                    # exit 4 if a teammate is on the same file
+scribeclock delivery                              # client project: push here, or is this the client's repo? (exit 4 = do not push)
 
 # Finishing
 scribeclock done #731 -m "Site live with SSL; checkout tested."   # runs .scribeclock.json checks first
@@ -154,8 +157,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/auth/lock.js

@@ -0,0 +1,55 @@
+import { createHash } from "node:crypto";
+import { closeSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { CliError } from "../cli/errors.js";
+/** Keep a rotating refresh token exclusive until its replacement is safely persisted. */
+export async function withRefreshLock(dir, profile, run) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const path = join(dir, `refresh-${createHash("sha256").update(profile).digest("hex")}.lock`);
+    const started = Date.now();
+    for (;;) {
+        try {
+            const fd = openSync(path, "wx", 0o600);
+            try {
+                writeFileSync(fd, String(process.pid));
+            }
+            finally {
+                closeSync(fd);
+            }
+            break;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            try {
+                const pid = Number(readFileSync(path, "utf8"));
+                if (Number.isInteger(pid) && pid > 0) {
+                    try {
+                        process.kill(pid, 0);
+                    }
+                    catch (err) {
+                        if (err.code === "ESRCH")
+                            unlinkSync(path);
+                    }
+                }
+                else if (Date.now() - statSync(path).mtimeMs > 30_000) {
+                    unlinkSync(path);
+                }
+            }
+            catch (err) {
+                if (err.code !== "ENOENT")
+                    throw err;
+            }
+            if (Date.now() - started > 30_000) {
+                throw new CliError("Another ScribeClock command is refreshing your session. Try again shortly.", { id: "refresh_busy" });
+            }
+            await new Promise((resolve) => setTimeout(resolve, 50));
+        }
+    }
+    try {
+        return await run();
+    }
+    finally {
+        unlinkSync(path);
+    }
+}

package/dist/auth/store.js

@@ -1,5 +1,6 @@
+import { randomUUID } from "node:crypto";
 import { execFile } from "node:child_process";
-import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { existsSync, readFileSync, renameSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { promisify } from "node:util";
 import { writeJsonPrivate } from "../config.js";
@@ -109,13 +110,24 @@ export class FileStore {
             return {};
         }
     }
+    writeAll(profiles) {
+        const temporary = `${this.path}.${randomUUID()}.tmp`;
+        try {
+            writeJsonPrivate(temporary, { version: 1, profiles });
+            renameSync(temporary, this.path);
+        }
+        finally {
+            if (existsSync(temporary))
+                unlinkSync(temporary);
+        }
+    }
     async load(profile) {
         return this.readAll()[profile] ?? null;
     }
     async save(profile, creds) {
         const all = this.readAll();
         all[profile] = creds;
-        writeJsonPrivate(this.path, { version: 1, profiles: all });
+        this.writeAll(all);
     }
     async clear(profile) {
         const all = this.readAll();
@@ -131,7 +143,7 @@ export class FileStore {
             }
             return;
         }
-        writeJsonPrivate(this.path, { version: 1, profiles: all });
+        this.writeAll(all);
     }
 }
 /**
@@ -177,8 +189,11 @@ export class ResilientStore {
         if (!this.usingFallback) {
             try {
                 const fromKeychain = await this.primary.load(profile);
-                if (fromKeychain)
-                    return fromKeychain;
+                const fromFile = await this.fallbackStore.load(profile);
+                // A failed keychain write can leave the rotated pair only in the fallback file.
+                if (fromFile && (!fromKeychain || fromFile.saved_at > fromKeychain.saved_at))
+                    return fromFile;
+                return fromKeychain ?? fromFile;
             }
             catch (err) {
                 this.degrade(err);
@@ -190,6 +205,7 @@ export class ResilientStore {
         if (!this.usingFallback && this.primary !== this.fallbackStore) {
             try {
                 await this.primary.save(profile, creds);
+                await this.fallbackStore.clear(profile);
                 return;
             }
             catch (err) {

package/dist/auth/token.js

@@ -1,9 +1,12 @@
-import { authError } from "../cli/errors.js";
+import { configDir } from "../config.js";
+import { withRefreshLock } from "./lock.js";
+import { CliError, authError } from "../cli/errors.js";
 import { refreshTokens, expiresAt } from "./oauth.js";
 /** Access tokens expire after 8 h; refresh this long before that so a call never lands on a dead token. */
 const REFRESH_SKEW_MS = 60 * 1000;
 export class TokenProvider {
     opts;
+    refreshing;
     cached;
     constructor(opts) {
         this.opts = opts;
@@ -35,40 +38,75 @@ export class TokenProvider {
         if (!creds)
             return null;
         if (creds.kind === "oauth" && creds.refresh_token && this.isExpiring(creds)) {
-            const refreshed = await this.refresh();
-            if (refreshed)
-                return refreshed;
+            try {
+                const refreshed = await this.refresh(creds.access_token);
+                if (refreshed)
+                    return refreshed;
+            }
+            catch (err) {
+                // A transient failure (network, 5xx, busy lock) must not break a token that still works.
+                const stillValid = !creds.expires_at || new Date(creds.expires_at).getTime() > this.now().getTime();
+                if (!stillValid || err.id === "auth")
+                    throw err;
+            }
         }
         return creds.access_token;
     }
-    /** Rotating refresh: both tokens are replaced and saved. A reused/revoked refresh token logs out. */
-    async refresh() {
+    /** Serialize rotation across providers and CLI processes, then reload the winning credentials. */
+    async refresh(rejectedToken) {
         if (this.opts.env.SCRIBECLOCK_TOKEN)
             return null;
-        const creds = await this.credentials();
-        if (!creds || creds.kind !== "oauth" || !creds.refresh_token || !creds.token_endpoint)
-            return null;
-        const result = await refreshTokens(this.opts.fetch, creds.token_endpoint, creds.refresh_token, creds.client_id);
-        if (!result.ok) {
-            if (result.error === "invalid_grant" || result.error === "invalid_client") {
-                await this.opts.store.clear(this.opts.profile);
-                this.cached = null;
-                throw authError("Your ScribeClock session was revoked or expired.", "Run `scribeclock login` to sign in again.");
-            }
-            return null;
+        if (this.refreshing)
+            return this.refreshing;
+        const pending = this.refreshLocked(rejectedToken);
+        this.refreshing = pending;
+        try {
+            return await pending;
+        }
+        finally {
+            this.refreshing = undefined;
         }
-        const next = {
-            ...creds,
-            access_token: result.tokens.access_token,
-            refresh_token: result.tokens.refresh_token ?? creds.refresh_token,
-            expires_at: expiresAt(result.tokens.expires_in, this.now()),
-            scopes: result.tokens.scope ? result.tokens.scope.split(/\s+/).filter(Boolean) : creds.scopes,
-            saved_at: this.now().toISOString(),
-        };
-        await this.opts.store.save(this.opts.profile, next);
-        this.cached = next;
-        this.opts.onRefreshed?.(next);
-        return next.access_token;
+    }
+    async refreshLocked(rejectedToken) {
+        const observed = await this.credentials();
+        const previous = rejectedToken ?? observed?.access_token;
+        return withRefreshLock(configDir(this.opts.env), this.opts.profile, async () => {
+            const creds = await this.opts.store.load(this.opts.profile);
+            this.cached = creds;
+            if (!creds)
+                return null;
+            if (previous && creds.access_token !== previous)
+                return creds.access_token;
+            if (creds.kind !== "oauth" || !creds.refresh_token || !creds.token_endpoint)
+                return null;
+            const result = await refreshTokens(this.opts.fetch, creds.token_endpoint, creds.refresh_token, creds.client_id);
+            if (!result.ok) {
+                if (result.error === "invalid_grant" || result.error === "invalid_client") {
+                    // Another process may have rotated the pair while we were waiting; use theirs if so.
+                    const latest = await this.opts.store.load(this.opts.profile);
+                    if (latest && latest.refresh_token !== creds.refresh_token) {
+                        this.cached = latest;
+                        return latest.access_token;
+                    }
+                    await this.opts.store.clear(this.opts.profile);
+                    this.cached = null;
+                    throw authError("Your ScribeClock session was revoked or expired.", "Run `scribeclock login` to sign in again.");
+                }
+                throw new CliError("Could not refresh your ScribeClock session. Try again in a moment.", { id: "refresh_failed" });
+            }
+            const next = {
+                ...creds,
+                access_token: result.tokens.access_token,
+                refresh_token: result.tokens.refresh_token ?? creds.refresh_token,
+                expires_at: expiresAt(result.tokens.expires_in, this.now()),
+                scopes: result.tokens.scope ? result.tokens.scope.split(/\s+/).filter(Boolean) : creds.scopes,
+                saved_at: this.now().toISOString(),
+            };
+            await this.opts.store.save(this.opts.profile, next);
+            this.cached = next;
+            this.opts.onRefreshed?.(next);
+            return next.access_token;
+        });
     }
     /** Forget the in-memory copy (after login/logout). */
     invalidate() {

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/ingest.js

@@ -121,12 +121,27 @@ sys.excepthook = lambda t, v, tb: report(v, level="fatal")`,
         },
     ];
 }
+/** The PostHog webhook body: the event, the person, and the link back to the PostHog issue. */
+export const POSTHOG_WEBHOOK_BODY = `{
+  "event": "{event}",
+  "person": "{person}",
+  "issue_url": "{project.url}/error_tracking/{event.properties.$exception_issue_id}"
+}`;
 /** Forward webhooks from an existing bug tracker (mirrors supabase/functions/_shared/ingestProviders.ts). */
 export function providerSetups(key) {
     const u = (p) => `${INGEST_URL}/${p}?key=${key}`;
     return [
         { id: "sentry", label: "Sentry", url: u("sentry"), steps: ["Alerts → Create Alert Rule → action “Send a notification via a webhook”, or Settings → Developer Settings → Internal Integrations → Webhook URL (issue + error webhooks on).", "Paste the URL. For an internal integration, store its Client Secret on the key: scribeclock update_ingest_key --key-id <id> --webhook-secret <secret>", "Each Sentry issue becomes one ScribeClock issue; the task links back to Sentry."] },
-        { id: "posthog", label: "PostHog", url: u("posthog"), steps: ["Data pipelines → Destinations → Webhook; keep the default body ({ event, person }).", "Filter on the $exception event for error tracking; other events are counted as analytics.", "Optional: header X-ScribeClock-Secret matching the key's webhook secret."] },
+        {
+            id: "posthog", label: "PostHog", url: `${INGEST_URL}/posthog`, headers: { "X-ScribeClock-Key": key }, body: POSTHOG_WEBHOOK_BODY,
+            steps: [
+                "Data pipelines → Destinations → New destination → HTTP Webhook. Paste the URL (no key in it).",
+                "Under secret headers add X-ScribeClock-Key with the ingest key — keys in URLs end up in logs and screenshots.",
+                "Replace the body with the one below: it adds issue_url, so each task links back to the PostHog issue (or: scribeclock update_ingest_key --key-id <id> --posthog-project-url https://us.posthog.com/project/<id>).",
+                "Filter on the $exception event for error tracking; any other event is counted as analytics.",
+                "Optional: --webhook-secret <signing secret>, --environment-property build_channel, --posthog-api-key phx_… (error_tracking:write: resolving here resolves in PostHog), --link-only true when the app also reports its own crashes.",
+            ],
+        },
         { id: "bugsnag", label: "Bugsnag", url: u("bugsnag"), steps: ["Project Settings → Integrations → Data forwarding → Webhook.", "Paste the URL and pick the triggers to forward (new, reopened, spikes).", "Optional shared secret: add ?secret=… to the URL and set the same value on the key."] },
         { id: "rollbar", label: "Rollbar", url: u("rollbar"), steps: ["Project → Settings → Notifications → Webhook.", "Paste the URL; enable new item / reactivated item / high occurrence rules.", "Optional shared secret: ?secret=… on the URL."] },
         { id: "crashlytics", label: "Firebase Crashlytics", url: u("crashlytics"), steps: ["Crashlytics has no outgoing webhook: add a Cloud Function on the Firebase Alerts trigger (onNewFatalIssuePublished, onRegressionAlertPublished, onNewNonfatalIssuePublished).", "POST { alertType, appId, payload } from the alert to this URL — snippet: https://scribeclock.com/help/bug-reports#forward", "Each Crashlytics issue becomes one ScribeClock issue with a link to the Firebase console."] },
@@ -137,7 +152,7 @@ export const ingestForward = cmd({
     path: "ingest forward",
     group: "Bug reports",
     summary: "Webhook URLs and steps to forward Sentry, PostHog, Bugsnag, Rollbar, Crashlytics or any tool's reports into this project.",
-    description: "Prints the per-provider URL (the ingest key rides in it, since most tools cannot set headers) and where to paste it. Each issue in the other tool becomes one ScribeClock issue and task that links back. Set a webhook secret on the key (update_ingest_key --webhook-secret) to verify Sentry signatures or a shared secret the tool echoes.",
+    description: "Prints the per-provider URL and where to paste it; the ingest key rides in the URL, except for PostHog, which takes it as the X-ScribeClock-Key secret header (plus the body to paste). Each issue in the other tool becomes one ScribeClock issue and task that links back. Set a webhook secret on the key (update_ingest_key --webhook-secret) to verify Sentry signatures or a shared secret the tool echoes.",
     tool: ["list_ingest_keys"],
     positionals: [{ name: "provider", description: "sentry, posthog, bugsnag, rollbar, crashlytics or webhook (default: all)." }],
     flags: [{ name: "key", alias: "k", type: "string", description: `Ingest key to embed (default: ${KEY_ENV} from the environment / .env).` }],
@@ -155,7 +170,11 @@ export const ingestForward = cmd({
         for (const p of providers) {
             ctx.out.log(ctx.out.bold(`── ${p.label}`));
             ctx.out.log(`  ${p.url}`);
+            for (const [h, v] of Object.entries(p.headers ?? {}))
+                ctx.out.log(`  header  ${h}: ${v}`);
             p.steps.forEach((s, i) => ctx.out.log(`  ${i + 1}. ${s}`));
+            if (p.body)
+                ctx.out.log(`  body:\n${p.body.replace(/^/gm, "    ")}`);
             ctx.out.log("");
         }
         if (key.startsWith("sc_ing_<"))

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/dist/commands/team.js

@@ -187,4 +187,36 @@ export const handoffRecord = cmd({
         });
     },
 });
-export const TEAM_COMMANDS = [teamCommand, overlapCommand, teamReport, handoffCommand, handoffRecord];
+export const deliveryCommand = cmd({
+    path: "delivery",
+    group: "Team",
+    summary: "Client hand-over: is this the team repository (push here, the client sees only your organization) or the client's (do not push)? Exits 4 in the client's repository, so it works as a pre-push hook.",
+    tool: "get_client_delivery",
+    flags: [REPO_FLAG],
+    async run(ctx, inv) {
+        const repo = repoOf(ctx, inv);
+        const data = await ctx.call("get_client_delivery", { repo });
+        const rows = (data.deliveries ?? []);
+        const d = rows[0];
+        const blocked = Boolean(d) && d.push_here !== true;
+        emit(ctx, data, () => {
+            if (!d) {
+                ctx.out.log(`${repo} is not handed over to a client: nothing republishes your commits under the organization's name.`);
+                return;
+            }
+            if (blocked)
+                ctx.out.warn(String(d.guidance ?? "Do not push here."));
+            else
+                ctx.out.log(ctx.out.bold(String(d.guidance ?? "")));
+            ctx.out.log("");
+            ctx.out.table(["team repository", "client's repository", "branch", "client sees", "status", "published"], [[d.team_repo, d.client_repo, d.published_branch, d.published_as, d.status, d.commits_published]].map((r) => r.map((v) => String(v ?? ""))));
+            for (const p of (d.problems ?? []))
+                ctx.out.warn(String(p));
+            if (!blocked)
+                for (const r of (d.rules ?? []))
+                    ctx.out.log(ctx.out.dim(`  • ${String(r)}`));
+        });
+        return blocked ? EXIT.CONFLICT : EXIT.OK;
+    },
+});
+export const TEAM_COMMANDS = [teamCommand, overlapCommand, teamReport, handoffCommand, handoffRecord, deliveryCommand];

package/dist/mcp/client.js

@@ -50,7 +50,7 @@ export class McpClient {
         const body = { jsonrpc: "2.0", id: this.nextId++, method, params };
         let res = await this.post(token, body);
         if (res.status === 401) {
-            const refreshed = await this.tokens.refresh();
+            const refreshed = await this.tokens.refresh(token);
             if (!refreshed) {
                 throw authError("Your ScribeClock session is no longer valid (the token was rejected).", "Run `scribeclock login` again. If you use SCRIBECLOCK_TOKEN, create a new personal access token.");
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scribeclock",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "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",