dirpush 0.1.7 → 0.2.0

package/.agents/skills/dirpush/SKILL.md

@@ -23,8 +23,8 @@ You are a **worker**, not the source of truth. SQLite (via the `dirpush` CLI) ow
    Something the human should do that doesn't stop the job (verify an email later, check a listing) → `dirpush todo add --job <job> --message "…" [--url …]`. It shows in the dashboard's Actions tab.
 10. **Hold your lease.** Checkpoints extend it; on long pages call `dirpush work heartbeat <job>` at least every 10 minutes. Stopping cleanly: `dirpush work release <job>`.
 11. **Browser = `dirpush ab <agent-browser command>`.** It drives the agents' own Chrome profile (logged into the human's Google account; Gmail, Drive and account pages blocked), never the human's everyday browser. Any agent that can run shell commands can use it. Never call `agent-browser` directly on that profile, never `network unroute`, never another browser tool or extension. Google sign-in rules in [authentication.md](references/authentication.md) are hard rules.
-   Habits: `dirpush ab open <url>`, `dirpush ab snapshot -i` (refs like `@e3`), `dirpush ab fill @e3 "text"`, `dirpush ab select`, `dirpush ab check`, `dirpush ab click`. Uploads: `dirpush ab upload '<input[type=file] selector>' <absolute path>`, never a button ref; sign in before uploading. Every call has a 90 s limit (`AB_TIMEOUT`); exit 142 = it hung: close that tab (`dirpush ab tab close`), reopen, continue from your last checkpoint. If every call hangs while one site is open (some pages freeze any automated browser on purpose), close that tab and `work block --type bot_protection` saying the human must submit it in their own browser; never close the whole browser for this.
-12. **Bot checks: wait, don't fight.** Cloudflare / Turnstile usually clears by itself in this Chrome: wait ~10 s and re-snapshot. Never click a CAPTCHA or Turnstile checkbox yourself and never use a solving service. Still there → `work block --type captcha` with the page left open. A plain arithmetic question in a form is part of the form: answer it.
+   Habits: `dirpush ab open <url>`, `dirpush ab snapshot -i` (refs like `@e3`), `dirpush ab fill @e3 "text"`, `dirpush ab select`, `dirpush ab check`, `dirpush ab click`. Uploads: `dirpush ab upload '<input[type=file] selector>' <absolute path>`, never a button ref; sign in before uploading. Every call has a 90 s limit (`AB_TIMEOUT`); exit 142 = it hung: close that tab (`dirpush ab tab close`), reopen, continue from your last checkpoint. If every call hangs while one site is open (some pages freeze any automated browser on purpose), close that tab and `work block --type bot_protection --message "<Site> breaks under automation. Do it in your own browser: <the steps, with the URL>"` (that phrase makes it a by-hand hand-off); never close the whole browser for this.
+12. **Bot checks: wait, don't fight.** Cloudflare / Turnstile usually clears by itself in this Chrome: wait ~10 s and re-snapshot. Never click a CAPTCHA or Turnstile checkbox yourself and never use a solving service. Still there → `work block --type captcha` with the page left open; it becomes a hand-off (below). A plain arithmetic question in a form is part of the form: answer it.
 13. **Close your browser** (`dirpush ab close`) when you stop, unless a job of yours is blocked on the human in that window (CAPTCHA, login) — leave it for them. A throwaway profile (`AB_PROFILE`) loses the filled form when closed: in the block message, list exactly what to re-enter.
 
 ## Loop
@@ -61,14 +61,30 @@ Workers read `dirpush capabilities` at the start of a session: email verificatio
 - **"Set up dirpush"** / **"set up this product"** / **"add a product"**: `dirpush init <product-id>`, run the Setup check above if `dirpush capabilities` says it hasn't been done, then help the user fill `workspace/products/<id>/product.yaml` (and the shared `workspace/identity.yaml`, `permissions.yaml` the first time). Validate with `dirpush product show --product <id>`.
 - **"Find N free directories I haven't submitted to and submit"**: `dirpush directories recommend --free --unsubmitted --limit N --product <id>`, show the list, `dirpush submissions enqueue <dir-id…> --product <id>`, then run the loop.
 - **"Continue my launch"**: the whole routine, no other instructions needed (nothing from a previous conversation is either):
-  1. `dirpush actions` — tell the human what's waiting on them. Google sign-in, CAPTCHAs and bot checks: tell them to run `dirpush checks` in their terminal (it walks them through each one and hands the jobs back); never solve them yourself.
+  1. `dirpush actions` — note what's waiting on the human; if they're here, do the **hand-offs** below with them now (before step 3, so their jobs join the loop).
   2. `dirpush submissions check` — marks pending listings live (skip if run in the last day).
   3. Run the loop until `work next` is empty. Jobs still showing another worker with an expired lease are abandoned: `work next` hands them to you; continue from their last step.
   4. Queue empty → `dirpush directories recommend --free --unsubmitted --limit 10 --product <id>`, show the list, enqueue only what the human approves.
   5. `dirpush capabilities` has no email tool, or you don't have that tool this session → verification steps are a `work block --type email_verification` with what to click, never a wait.
+- **"What do you need from me?"** / the human is around and `dirpush handoff list` isn't empty: do the hand-offs below.
 - **"Add a directory I submitted to myself"**: `dirpush submissions add <directory-id or URL> --listing-url <url> [--outcome live|pending]`.
 - New directories go upstream: tell the human to report them on the dirpush repository; the registry is not researched locally.
 
+## Hand-offs: the human's part, done with you in chat
+
+The human never needs the CLI. Some steps only they can do: sign into Google once, tick a bot check, or (rarely) submit by hand on a site that breaks under automation. You walk them through these one at a time, in chat:
+
+1. `dirpush handoff next` opens the page itself (Google's sign-in window, the agents' Chrome on the check, or their own browser for a by-hand site) and returns `ask`: one sentence. Say exactly that. For a by-hand site it also returns `paste`: give them those values to copy.
+2. Wait for their reply. Never solve a CAPTCHA or bot check yourself, and don't poll the page while they work.
+3. Their answer:
+   - "done" → `dirpush handoff done <job>` (`google` for the sign-in, which hands back every Google job), then **claim that job and finish it right away**, in the same tab, before the page goes stale. Then the next hand-off.
+   - submitted it themselves → `dirpush handoff mine <job> [--listing-url <url>]`.
+   - "not now" / "skip" → `dirpush handoff skip <job>` (hidden from `next` for 12 hours).
+   - "stop" → stop asking; the rest stays in `dirpush handoff list` for next time.
+4. Keep it short: one hand-off per message, no lists of commands, no internal job ids unless they ask. If the human isn't around, don't start hand-offs; mention how many are waiting at the end.
+
+A human who prefers the terminal can run plain `dirpush handoff` to walk the same queue themselves; then `continue my launch` finishes what they cleared.
+
 ## Command reference
 
 `dirpush help` lists every command with a one-line description. Output is compact JSON on stdout: list rows are short (ids, states, 200-char messages, ISO times), and only `work next`, `work show` and `wait` include a job's saved `data`. Lists stop at 50 rows. When something is cut short or empty, a `note:` line on stderr says why and how to narrow it; read it. `--full` returns raw rows, `--pretty` indents. The most used:

package/README.md

@@ -15,23 +15,31 @@ npm i -g dirpush agent-browser   # or run everything below with npx
 dirpush init acme                # sets up ~/.dirpush and installs the agent skill
 ```
 
-`init` keeps your launch in `~/.dirpush` (database, product files, the agents' Chrome profile) and installs the dirpush skill for your agents in `~/.claude/skills` and `~/.agents/skills`. Then open your agent and say **"set up dirpush"**: it fills in your product's facts with you and checks which tools it has, such as an email tool for verification links. After that, **"continue my launch"** runs the whole loop. `dirpush serve` opens the dashboard.
+`init` keeps your launch in `~/.dirpush` (database, product files, the agents' Chrome profile) and installs the dirpush skill for your agents in `~/.claude/skills` and `~/.agents/skills`. That's the only command you need.
 
-## Useful commands
+## Talk to your agent
+
+| Say | What happens |
+| --- | --- |
+| **"set up dirpush"** | It fills in your product's facts with you and checks its tools (an email tool for verification links, the browser). |
+| **"continue my launch"** | It finds directories that fit, submits, verifies emails, re-checks pending listings, and records everything. |
+| **"what do you need from me?"** | It walks you through the few things only you can do, one at a time: sign into Google once, tick a bot check in a window it opens, rarely submit a site by hand. You answer "done" and it carries on. |
+| **"how is my launch going?"** | Live, pending and rejected listings, and what's waiting. |
+
+Agents never solve CAPTCHAs, never pay, and ask before anything your `permissions.yaml` marks as "confirm". `dirpush serve` opens a local dashboard if you want to look around.
+
+## The CLI, if you want it
+
+Agents drive everything below; you never have to. `dirpush help` lists it all.
 
 | Command | Purpose |
 | --- | --- |
-| `dirpush directories recommend --free --unsubmitted --product <id>` | Directories that fit and haven't been tried |
+| `dirpush actions` | What's waiting on you |
+| `dirpush handoff` | Walk your part yourself in the terminal instead of in chat |
 | `dirpush submissions list --product <id>` | Every submission and its outcome |
-| `dirpush submissions check` | Re-check pending listings and mark live ones |
-| `dirpush actions` | What needs you: CAPTCHAs, verification emails, questions |
-| `dirpush checks` | Your part, guided: sign into Google, then clear CAPTCHAs and bot checks one by one; agents pick each job back up |
+| `dirpush directories recommend --free --unsubmitted --product <id>` | Directories that fit and haven't been tried |
 | `dirpush registry updates [--apply]` | Update your registry from the published one on dirpush.com |
-| `dirpush registry audit` | Measure link type, noindex and bot checks on real listing pages |
-| `dirpush submissions add <id or URL>` | Record a listing you made yourself |
-| `dirpush dr refresh` / `dirpush dr show` | Optional Ahrefs Domain Rating history (needs `AHREFS_API_KEY`) |
-
-`dirpush help` lists everything.
+| `dirpush dr show` | Domain Rating history (optional, needs `AHREFS_API_KEY`) |
 
 ## Working on dirpush
 

package/package.json

@@ -37,7 +37,7 @@
     "url": "https://github.com/baronunread/dirpush.git"
   },
   "homepage": "https://dirpush.com",
-  "version": "0.1.7",
+  "version": "0.2.0",
   "keywords": [
     "directories",
     "startup",

package/src/cli.ts

@@ -19,7 +19,8 @@ import { auditDirectory, auditDirectoryBrowser } from "./audit";
 import { browserStatus, newPassword, startBrowser, stopBrowser, vaultLogin } from "./browser";
 import { accountsFor, backfillAccounts, listAccounts } from "./accounts";
 import { detect, loadCapabilities, saveCapabilities } from "./capabilities";
-import { checks } from "./checks";
+import { handoffDone, handoffMine, handoffNext, handoffQueue, handoffSkip } from "./handoff";
+import { walk } from "./walk";
 import { ratingDomain, ratingHistory, refreshRatings } from "./ratings";
 import { fetchRegistryFile, registrySource, registryUpdates } from "./registry-updates";
 import { loadIdentity, loadPermissions, loadProduct, permission, productIds, resolveProductId, PRODUCTS, utm, WORKSPACE } from "./workspace";
@@ -37,7 +38,7 @@ if (first === "--version" || first === "-v") {
 }
 if (first === "--help" || first === "-h") process.argv.splice(2, 1, "help");
 // Names people type for the human-facing commands.
-const ALIASES: Record<string, string> = { check: "checks", captchas: "checks", needs: "actions", todos: "actions" };
+const ALIASES: Record<string, string> = { checks: "handoff", check: "handoff", captchas: "handoff", needs: "actions", todos: "actions" };
 if (first && ALIASES[first]) process.argv.splice(2, 1, ALIASES[first]);
 /** Agents read JSON errors; a person at a terminal gets a plain sentence. */
 function fail(error: string, extra: { didYouMean?: string[] } = {}): never {
@@ -537,7 +538,17 @@ const commands: Record<string, (() => Promise<unknown> | unknown) | undefined> =
   },
   "assets capture-complete": () => consumeProductApproval(db, Number(arg(0, "approval-id"))),
   /** The human's part, interactive: Google sign-in, then CAPTCHAs and bot checks one by one (src/checks.ts). */
-  "checks": async () => { await checks(db, { product: flags.product, types: (flags.type ?? "captcha,bot_protection").split(",").map((t) => t.trim()) }); process.exit(0); },
+  // Hand-offs (src/handoff.ts): agents call next/done/mine/skip and talk the human through it in chat;
+  // a human at a terminal can run plain `dirpush handoff` to walk the same queue.
+  "handoff": async () => {
+    if (process.stdin.isTTY && process.stdout.isTTY) { await walk(db, flags.product); process.exit(0); }
+    return handoffQueue(db, flags.product);
+  },
+  "handoff list": () => handoffQueue(db, flags.product, { includeSkipped: flags.all }),
+  "handoff next": () => handoffNext(db, flags.product),
+  "handoff done": () => handoffDone(db, arg(0, "job or google")),
+  "handoff mine": () => handoffMine(db, arg(0, "job"), flags["listing-url"]),
+  "handoff skip": () => handoffSkip(db, arg(0, "job")),
 
   /** Everything waiting on the human, grouped. --product narrows it. */
   "actions": () => {
@@ -677,7 +688,9 @@ const HELP: [string, [string, string][]][] = [
     ["products list", "all products in this workspace"],
     ["permission <group.action>", "automatic | confirm | never for an action, e.g. accounts.oauth_google"],
     ["actions [--product id]", "everything waiting on the human, grouped"],
-    ["checks [--type captcha,bot_protection] [--product id]", "for the human: sign into Google, then clear CAPTCHAs and bot checks one by one; each job goes back to the agents"],
+    ["handoff next [--product id]", "the next thing only the human can do (Google sign-in, a bot check, a by-hand site): opens it and returns the sentence to say in chat"],
+    ["handoff done <job|google> | mine <job> [--listing-url u] | skip <job>", "the human answered: hand the job back (then finish it now), they submitted it themselves, or not now"],
+    ["handoff list [--all]", "everything waiting on the human (a person at a terminal: plain 'dirpush handoff' walks it)"],
   ]],
   ["Work loop", [
     ["work next [--claim]", "next submission job (unknown ones first); --claim leases it to you"],

package/src/handoff.ts

@@ -0,0 +1,120 @@
+/**
+ * Hand-offs: the bits of a submission only the human can do (sign into Google, tick a bot check, or fill a form on a
+ * site that breaks under automation). Agent-first: the agent calls `handoff next`, which opens the page and returns
+ * one sentence to relay in chat; when the human answers, `handoff done` hands the job back and the agent finishes it
+ * right away, in the same window. `dirpush handoff` in a terminal walks a human through the same queue (src/walk.ts).
+ */
+import { join } from "node:path";
+import { and, eq, gt, inArray } from "drizzle-orm";
+import { HOME, PKG, type Db } from "./db";
+import { events, jobs, type Job } from "./db/schema";
+import * as J from "./jobs";
+import { loadDirectory } from "./registry";
+import { loadProduct, utm } from "./workspace";
+
+export type Kind = "google_login" | "tick" | "own_browser";
+/** `ask`: what the agent says in chat. `todo`: the same, short, for the terminal walk. */
+export type Handoff = { kind: Kind; jobs: string[]; directory: string; name: string; url?: string; ask: string; todo: string };
+
+const TICK = ["captcha", "bot_protection"];
+const SKIP_HOURS = 12;
+const env = { ...process.env, LAUNCH_HOME: HOME };
+export const script = (name: string, ...args: string[]) =>
+  Bun.spawnSync([join(PKG, "scripts", name), ...args], { env, stdin: "ignore", stdout: "ignore", stderr: "ignore" }).exitCode;
+
+/** Sites that break under automation: the agent's block message says the human must use their own browser. */
+export const ownBrowser = (job: Job) => /your own browser/i.test(job.blockMessage ?? "");
+const firstUrl = (s?: string | null) => s?.match(/https?:\/\/[^\s)'"”]+/)?.[0]?.replace(/[.,;:]$/, "");
+/** The human's instruction from a block message written for them ("… in your own browser: <this>, then press s …"). */
+const instruction = (job: Job) =>
+  (job.blockMessage ?? "").split(/your own browser:?/i)[1]?.trim().replace(/,?\s*then press s in dirpush (checks|handoff)\.?$/i, "").replace(/\.$/, "") || "submit it";
+
+function skippedRecently(db: Db) {
+  const since = Date.now() - SKIP_HOURS * 3600_000;
+  return new Set(db.select().from(events).where(and(eq(events.type, "handoff_skipped"), gt(events.at, since))).all().map((e) => e.jobId));
+}
+
+/** What's waiting on the human, in order: one Google sign-in for all directories that need it, then each check. */
+export async function handoffQueue(db: Db, product?: string, opts: { includeSkipped?: boolean } = {}): Promise<Handoff[]> {
+  const skipped = opts.includeSkipped ? new Set<string | null>() : skippedRecently(db);
+  const blocked = db.select().from(jobs)
+    .where(and(eq(jobs.kind, "submission"), eq(jobs.status, "blocked"), inArray(jobs.blockType, ["google_login", ...TICK]))).all()
+    .filter((j) => (!product || j.productId === product) && !skipped.has(j.id));
+  const out: Handoff[] = [];
+  const google = blocked.filter((j) => j.blockType === "google_login");
+  if (google.length) out.push({
+    kind: "google_login", jobs: google.map((j) => j.id), directory: "google", name: "Google sign-in",
+    todo: "A Chrome window opens: sign in, then quit it with ⌘Q.",
+    ask: `A Chrome window is open on Google's sign-in page. Sign in, then quit that window with ⌘Q and tell me. (${google.length} ${google.length === 1 ? "directory needs" : "directories need"} it.)`,
+  });
+  for (const job of blocked.filter((j) => TICK.includes(j.blockType ?? ""))) {
+    const dir = await loadDirectory(job.subject).then((d) => d.directory).catch(() => null);
+    const name = dir?.name ?? job.subject;
+    const url = firstUrl(job.blockMessage) ?? dir?.submission_url ?? dir?.website;
+    out.push(ownBrowser(job)
+      ? { kind: "own_browser", jobs: [job.id], directory: job.subject, name, url, todo: `Do this one in your own browser: ${instruction(job)}.`,
+          ask: `${name} breaks when an agent drives the browser, so this one's by hand. I opened it in your browser: ${instruction(job)}. Tell me when it's submitted, with the listing link if there is one.` }
+      : { kind: "tick", jobs: [job.id], directory: job.subject, name, url, todo: "Tick the box in the window that opened. No box? Just press enter.",
+          ask: `A Chrome window is open on ${name}. Tick the box if you see one (no box is fine too), then tell me "done".` });
+  }
+  return out;
+}
+
+/** Opens the page for a hand-off: plain Chrome for Google, the agents' Chrome for a check, the human's browser otherwise. */
+export function openHandoff(h: Handoff) {
+  if (h.kind === "google_login") {
+    // Blocks until the human quits that window, so detach: the agent waits for the human's reply in chat instead.
+    Bun.spawn([join(PKG, "scripts/google-login")], { env, stdin: "ignore", stdout: "ignore", stderr: "ignore" }).unref();
+    return true;
+  }
+  if (!h.url) return false;
+  if (h.kind === "own_browser") return Bun.spawnSync(["open", h.url]).exitCode === 0;
+  if (script("ab", "open", h.url) !== 0) return false;
+  script("show-browser");
+  return true;
+}
+
+/** For the agent: the next hand-off, opened, with the sentence to relay and (by hand) the facts to paste. */
+export async function handoffNext(db: Db, product?: string) {
+  const [h, ...rest] = await handoffQueue(db, product);
+  if (!h) return { next: null, note: "nothing waiting on the human" };
+  const opened = openHandoff(h);
+  const paste = h.kind === "own_browser" ? await pasteFacts(db, h.jobs[0]!) : undefined;
+  return {
+    ...h, opened, ...(paste && { paste }), remaining: rest.length,
+    then: h.kind === "own_browser"
+      ? `when they say it's submitted: dirpush handoff mine ${h.jobs[0]} [--listing-url <url>]`
+      : `when they say done: dirpush handoff done ${h.kind === "google_login" ? "google" : h.jobs[0]}, then claim and finish ${h.kind === "google_login" ? "those jobs" : "it now, in the same tab"}`,
+    ...(!opened && h.url && { note: `couldn't open the page; give the human this link: ${h.url}` }),
+  };
+}
+
+async function pasteFacts(db: Db, jobId: string) {
+  const job = db.select().from(jobs).where(eq(jobs.id, jobId)).get();
+  if (!job) return undefined;
+  const p = await loadProduct(job.productId).catch(() => null);
+  if (!p) return undefined;
+  return {
+    name: p.name, website: utm(p.url, job.subject), tagline: p.tagline,
+    short: p.descriptions?.short, description: p.descriptions?.medium, categories: p.categories,
+    logo: p.assets?.icon ? join(p.dir, p.assets.icon) : undefined,
+  };
+}
+
+/** The human did their part: hand the job(s) back to the agents. `google` hands back every Google sign-in job. */
+export function handoffDone(db: Db, id: string) {
+  const ids = id === "google"
+    ? db.select().from(jobs).where(and(eq(jobs.status, "blocked"), eq(jobs.blockType, "google_login"))).all().map((j) => j.id)
+    : [id];
+  const note = id === "google" ? "human signed into Google in the agents' Chrome profile" : "human cleared the check in the agents' Chrome; continue in the same tab";
+  return { handedBack: ids.map((j) => J.unblock(db, j, note)).map((j) => ({ id: j.id, directory: j.subject })), then: "claim each and finish it now" };
+}
+
+/** The human submitted it themselves. */
+export const handoffMine = (db: Db, id: string, listingUrl?: string) => J.recordManual(db, id, "pending", listingUrl);
+
+/** Not now: leave it blocked, out of `handoff next` for a while. */
+export function handoffSkip(db: Db, id: string) {
+  J.noteEvent(db, id, "handoff_skipped");
+  return { skipped: id, until: new Date(Date.now() + SKIP_HOURS * 3600_000).toISOString() };
+}

package/src/jobs.ts

@@ -16,6 +16,11 @@ function logEvent(tx: Tx | Db, jobId: string | null, type: string, worker: strin
   tx.insert(events).values({ jobId, type, worker, data }).run();
 }
 
+/** A plain event on a job (no state change), e.g. a hand-off the human skipped. */
+export function noteEvent(db: Db, jobId: string, type: string, data: Record<string, unknown> = {}) {
+  logEvent(db, jobId, type, "human", data);
+}
+
 function get(tx: Tx, id: string): Job {
   const job = tx.select().from(jobs).where(eq(jobs.id, id)).get();
   if (!job) throw new JobError(`no such job: ${id}`);

package/src/walk.ts

@@ -0,0 +1,92 @@
+/**
+ * `dirpush handoff` in a terminal: the human walks the hand-off queue themselves (src/handoff.ts), for anyone who
+ * prefers that to their agent walking them through it in chat. Same queue, same effect on the jobs.
+ */
+import { createInterface } from "node:readline/promises";
+import type { Db } from "./db";
+import * as J from "./jobs";
+import { loadCapabilities } from "./capabilities";
+import { handoffDone, handoffQueue, handoffSkip, openHandoff, script } from "./handoff";
+
+const color = process.stdout.isTTY && !process.env.NO_COLOR;
+const paint = (code: string) => (s: string) => (color ? `\x1b[${code}m${s}\x1b[0m` : s);
+const bold = paint("1"), dim = paint("2"), green = paint("32"), yellow = paint("33"), cyan = paint("36");
+
+/** One keypress, no Enter needed. Enter comes back as "\r"; Ctrl-C quits. */
+async function key(prompt: string, keys: string): Promise<string> {
+  process.stdout.write(prompt);
+  process.stdin.setRawMode(true);
+  process.stdin.resume();
+  try {
+    for (;;) {
+      const k = await new Promise<string>((r) => process.stdin.once("data", (b: Buffer) => r(b.toString())));
+      if (k === "\x03") { process.stdout.write("\n"); process.exit(130); }
+      const ch = k === "\r" || k === "\n" ? "\r" : k.toLowerCase();
+      if (keys.includes(ch)) { process.stdout.write(ch === "\r" ? "\n" : `${ch}\n`); return ch; }
+    }
+  } finally {
+    process.stdin.setRawMode(false);
+    process.stdin.pause();
+  }
+}
+
+async function ask(prompt: string) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try { return (await rl.question(prompt)).trim(); } finally { rl.close(); }
+}
+
+export async function walk(db: Db, product?: string) {
+  if (!process.stdin.isTTY) throw new Error("this is the interactive version: run 'dirpush handoff' in a terminal, or let your agent use 'handoff next'");
+  const items = await handoffQueue(db, product, { includeSkipped: true });
+  if (!items.length) return console.log("Nothing is waiting on you.");
+  console.log(`${bold("dirpush handoff")} ${dim(`· ${items.length} to clear · an agent finishes each one after you`)}`);
+  const host = (u: string) => u.replace(/^https?:\/\/(www\.)?/, "").replace(/\/$/, "");
+  const keys = (pairs: [string, string][]) => `      ${pairs.map(([k, l]) => `${cyan(k)} ${l}`).join("   ")}  `;
+  let back = 0, mine = 0, skipped = 0;
+
+  for (const [i, h] of items.entries()) {
+    const where = h.kind === "google_login" ? `${h.jobs.length} ${h.jobs.length === 1 ? "directory" : "directories"}` : h.url ? host(h.url) : "";
+    console.log(`\n${dim(`${i + 1}/${items.length}`)}  ${bold(h.name)}  ${dim(where)}\n      ${h.todo}`);
+    if (h.kind === "google_login") {
+      const k = await key(keys([["enter", "sign in"], ["n", "later"], ["q", "quit"]]), "\rnq");
+      if (k === "q") break;
+      if (k === "n") { skipped++; continue; }
+      console.log(dim("      Waiting for you to quit that Chrome window…"));
+      script("google-login"); // returns when that Chrome quits
+      if ((await key(`      Signed in?  ${cyan("y")} yes   ${cyan("n")} no  `, "yn")) === "y") { back += handoffDone(db, "google").handedBack.length; } else skipped++;
+      continue;
+    }
+    if (!openHandoff(h) && h.url) console.log(yellow(`      Couldn't open it; go to ${h.url}`));
+    const byHand = h.kind === "own_browser";
+    const k = await key(keys(byHand ? [["s", "done"], ["n", "skip"], ["q", "quit"]] : [["enter", "done"], ["s", "I submitted it myself"], ["n", "skip"], ["q", "quit"]]), byHand ? "snq" : "\rsnq");
+    if (k === "q") break;
+    const id = h.jobs[0]!;
+    if (k === "n") { handoffSkip(db, id); skipped++; }
+    else if (k === "\r") { handoffDone(db, id); back++; }
+    else { const link = await ask(`      Listing link ${dim("(enter to skip)")}: `); J.recordManual(db, id, "pending", link || undefined); mine++; }
+  }
+  const parts = [back && `${back} back to the agents`, mine && `${mine} done by you`, skipped && `${skipped} skipped`].filter(Boolean);
+  console.log(`\n${green("✓")} ${bold("Done.")} ${parts.join(" · ") || "Nothing changed."}`);
+  if (back) await startAgent(back);
+}
+
+/** The agent CLIs we can open on "continue my launch", most likely first: the one that recorded capabilities, then any on PATH. */
+async function startAgent(n: number) {
+  const caps = await loadCapabilities().catch(() => null);
+  const known = [
+    { id: "claude-code", name: "Claude Code", bin: "claude" },
+    { id: "codex", name: "Codex", bin: "codex" },
+  ].filter((a) => Bun.which(a.bin));
+  const agent = known.find((a) => caps?.checked_by?.startsWith(a.id)) ?? known[0];
+  const prompt = "continue my launch";
+  if (!agent || process.platform !== "darwin") {
+    console.log(`Next: tell your agent ${bold(`“${prompt}”`)} to finish them.`);
+    return;
+  }
+  const k = await key(`  ${cyan("enter")} open ${agent.name} to finish them   ${cyan("n")} later  `, "\rn");
+  if (k === "n") return console.log(dim(`  Later: tell your agent “${prompt}”.`));
+  // A new Terminal window, so the human watches it work and approves what it asks for. Nothing runs unattended.
+  const cmd = `cd ${JSON.stringify(process.cwd())} && ${agent.bin} ${JSON.stringify(prompt)}`;
+  const ok = Bun.spawnSync(["osascript", "-e", `tell application "Terminal" to do script ${JSON.stringify(cmd)}`, "-e", `tell application "Terminal" to activate`], { stdin: "ignore", stdout: "ignore", stderr: "ignore" }).exitCode === 0;
+  console.log(ok ? `${green("✓")} Opened ${agent.name} in a new Terminal window.` : `Couldn't open Terminal. Run this yourself: ${cmd}`);
+}

package/src/checks.ts

@@ -1,153 +0,0 @@
-/**
- * `dirpush checks`: the human's part of a launch, in the terminal. Google sign-in first, in plain Chrome with no
- * automation attached (Google refuses sign-in in a window software is driving); then each CAPTCHA or bot check,
- * opened in the agents' Chrome. Agents never solve these: this hands each job back once the human has.
- */
-import { createInterface } from "node:readline/promises";
-import { join } from "node:path";
-import { and, eq, gt, inArray } from "drizzle-orm";
-import { HOME, PKG, type Db } from "./db";
-import { jobs } from "./db/schema";
-import * as J from "./jobs";
-import { loadCapabilities } from "./capabilities";
-import { loadDirectory } from "./registry";
-
-const color = process.stdout.isTTY && !process.env.NO_COLOR;
-const paint = (code: string) => (s: string) => (color ? `\x1b[${code}m${s}\x1b[0m` : s);
-const bold = paint("1"), dim = paint("2"), green = paint("32"), yellow = paint("33"), cyan = paint("36");
-const env = { ...process.env, LAUNCH_HOME: HOME };
-const script = (name: string, ...args: string[]) =>
-  Bun.spawnSync([join(PKG, "scripts", name), ...args], { env, stdin: "ignore", stdout: "ignore", stderr: "ignore" }).exitCode;
-
-/** One keypress, no Enter needed. Enter comes back as "\r"; Ctrl-C quits. */
-async function key(prompt: string, keys: string): Promise<string> {
-  process.stdout.write(prompt);
-  process.stdin.setRawMode(true);
-  process.stdin.resume();
-  try {
-    for (;;) {
-      const k = await new Promise<string>((r) => process.stdin.once("data", (b: Buffer) => r(b.toString())));
-      if (k === "\x03") { process.stdout.write("\n"); process.exit(130); }
-      const ch = k === "\r" || k === "\n" ? "\r" : k.toLowerCase();
-      if (keys.includes(ch)) { process.stdout.write(ch === "\r" ? "\n" : `${ch}\n`); return ch; }
-    }
-  } finally {
-    process.stdin.setRawMode(false);
-    process.stdin.pause();
-  }
-}
-
-async function ask(prompt: string) {
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  try { return (await rl.question(prompt)).trim(); } finally { rl.close(); }
-}
-
-const WHAT: Record<string, string> = {
-  captcha: "Tick the CAPTCHA, then do whatever the note above asks.",
-  bot_protection: "Wait for the “checking your browser” page to pass, or tick its box if it shows one.",
-};
-
-export async function checks(db: Db, opts: { product?: string; types: string[] }) {
-  if (!process.stdin.isTTY) throw new Error("checks is interactive: run `dirpush checks` yourself in a terminal");
-  const blocked = (types: string[]) => db.select().from(jobs)
-    .where(and(eq(jobs.kind, "submission"), eq(jobs.status, "blocked"), inArray(jobs.blockType, types))).all()
-    .filter((j) => !opts.product || j.productId === opts.product);
-  const google = blocked(["google_login"]);
-  const queue = blocked(opts.types);
-  const handedBack: string[] = [], byYou: string[] = [], skipped: string[] = [];
-  let signedIn = false;
-
-  const summary = async () => {
-    console.log(`\n${bold("Done for now.")}`);
-    if (handedBack.length) console.log(`${green("✓")} Ready for the agents to finish: ${handedBack.join(", ")}`);
-    if (byYou.length) console.log(`${green("✓")} Submitted by you: ${byYou.join(", ")}`);
-    if (skipped.length) console.log(`${dim("·")} Skipped, still waiting: ${skipped.join(", ")}`);
-    if (handedBack.length) await startAgent(handedBack.length);
-  };
-
-  const googleSignIn = async () => {
-    const busy = db.select().from(jobs).where(and(eq(jobs.status, "running"), gt(jobs.leaseExpiresAt, Date.now()))).all();
-    if (busy.length) {
-      console.log(yellow(`An agent is using the browser right now (${busy.map((j) => j.subject).join(", ")}). Signing in closes that window.`));
-      if ((await key(`${cyan("[enter]")} close it and sign in   ${cyan("[n]")} not now `, "\rn")) === "n") return false;
-    }
-    console.log(`A normal Chrome window opens on Google's sign-in page (the agents' own profile, nothing automated).`);
-    console.log(`Sign in, then ${bold("quit that window with ⌘Q")} to come back here.`);
-    script("google-login"); // returns when that Chrome quits
-    const ok = (await key(`Signed in?  ${cyan("[y]")} yes   ${cyan("[n]")} no `, "yn")) === "y";
-    if (ok) signedIn = true;
-    else console.log(dim("No problem: run `dirpush checks` again whenever you want to retry."));
-    return ok;
-  };
-
-  console.log(`${bold("dirpush checks")}  ${dim(`${google.length} need Google sign-in · ${queue.length} CAPTCHAs or bot checks`)}`);
-  if (!google.length && !queue.length) return console.log("Nothing is waiting on you.");
-  console.log(dim("Agents never solve these. You clear each one, then an agent finishes the submission (at the end I can start yours)."));
-
-  if (google.length) {
-    console.log(`\n${bold("1. Sign into Google")}  ${dim(google.map((j) => j.subject).join(", "))}`);
-    console.log("These directories use “Sign in with Google”. Sign in once and the agents can use it from then on.");
-    const k = await key(`${cyan("[enter]")} sign in now   ${cyan("[n]")} later   ${cyan("[q]")} quit `, "\rnq");
-    if (k === "q") return await summary();
-    if (k === "\r" && (await googleSignIn())) {
-      for (const j of google) { J.unblock(db, j.id, "human signed into Google in the agents' Chrome profile"); handedBack.push(j.subject); }
-    } else skipped.push(...google.map((j) => j.subject));
-  }
-
-  for (const [i, job] of queue.entries()) {
-    const dir = await loadDirectory(job.subject).then((d) => d.directory).catch(() => null);
-    const url = job.blockMessage?.match(/https?:\/\/[^\s)'"”]+/)?.[0]?.replace(/[.,;:]$/, "") ?? dir?.submission_url ?? dir?.website;
-    const open = () => {
-      if (!url) return console.log(yellow("No page saved for this one; open the directory yourself."));
-      if (script("ab", "open", url) === 0) script("show-browser");
-      else console.log(yellow(`Couldn't open the agents' Chrome. Open it yourself: ${url}`));
-    };
-    console.log(`\n${bold(`${google.length ? i + 2 : i + 1}. ${dir?.name ?? job.subject}`)}  ${dim(`${i + 1} of ${queue.length}`)}`);
-    if (job.blockMessage) console.log(dim(job.blockMessage));
-    if (url) console.log(`${dim("Page:")} ${url}`);
-    console.log(WHAT[job.blockType ?? ""] ?? "Do what the note above asks.");
-    console.log(dim("Asked to sign in with Google? Press g: Google refuses sign-in in the agents' window."));
-    console.log(dim("Check never passes there? Submit it from your own browser instead, then press s."));
-    open();
-    for (;;) {
-      const k = await key(`${cyan("enter")} cleared, agent finishes it  ${cyan("s")} I submitted it  ${cyan("o")} reopen  ${cyan("g")} Google sign-in  ${cyan("n")} skip  ${cyan("q")} quit › `, "\rsognq");
-      if (k === "o") { open(); continue; }
-      if (k === "g") { if (!signedIn) await googleSignIn(); open(); continue; }
-      if (k === "q") return await summary();
-      if (k === "n") skipped.push(job.subject);
-      else if (k === "\r") {
-        J.unblock(db, job.id, "human cleared the check in the agents' Chrome; continue in the same browser session");
-        handedBack.push(job.subject);
-      } else {
-        const link = await ask(`Listing URL, if there is one ${dim("(enter to skip)")}: `);
-        J.recordManual(db, job.id, "pending", link || undefined);
-        byYou.push(job.subject);
-      }
-      break;
-    }
-  }
-  await summary();
-}
-
-
-/** The agent CLIs we can open on "continue my launch", most likely first: the one that recorded capabilities, then any on PATH. */
-async function startAgent(n: number) {
-  const caps = await loadCapabilities().catch(() => null);
-  const known = [
-    { id: "claude-code", name: "Claude Code", bin: "claude" },
-    { id: "codex", name: "Codex", bin: "codex" },
-  ].filter((a) => Bun.which(a.bin));
-  const agent = known.find((a) => caps?.checked_by?.startsWith(a.id)) ?? known[0];
-  const prompt = "continue my launch";
-  if (!agent || process.platform !== "darwin") {
-    console.log(`\nNext: open your agent and say ${bold(`“${prompt}”`)}; it finishes the ${n} job(s) above.`);
-    return;
-  }
-  console.log(`\nThe ${n} job(s) above are waiting for an agent to finish them.`);
-  const k = await key(`${cyan("[enter]")} open ${agent.name} on “${prompt}” now   ${cyan("[n]")} I'll do it later `, "\rn");
-  if (k === "n") return console.log(dim(`Whenever you're ready: open your agent and say “${prompt}”.`));
-  // A new Terminal window, so the human watches it work and approves what it asks for. Nothing runs unattended.
-  const cmd = `cd ${JSON.stringify(process.cwd())} && ${agent.bin} ${JSON.stringify(prompt)}`;
-  const ok = Bun.spawnSync(["osascript", "-e", `tell application "Terminal" to do script ${JSON.stringify(cmd)}`, "-e", `tell application "Terminal" to activate`], { stdin: "ignore", stdout: "ignore", stderr: "ignore" }).exitCode === 0;
-  console.log(ok ? `${green("✓")} Opened ${agent.name} in a new Terminal window.` : `Couldn't open Terminal. Run this yourself: ${cmd}`);
-}