convene-cli 1.11.0 → 1.13.0

package/dist/commands/auth.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.assessWatchHealth = assessWatchHealth;
 exports.login = login;
 exports.whoami = whoami;
 exports.assessLaneIdentity = assessLaneIdentity;
@@ -54,6 +55,41 @@ function relaunchWatch(slug) {
         return false;
     }
 }
+/**
+ * PURE health verdict for the `doctor` "watch" line (unit-tested, no I/O). The
+ * watcher is a BEST-EFFORT liveness/notify daemon: it self-terminates once its
+ * owning session goes idle (~30m — see watch.ts) and is only relaunched at the
+ * next SessionStart, so a stale/absent heartbeat is the EXPECTED state for any
+ * quiet or long-lived session, NOT an error. Directed halts still surface via the
+ * pull path (fetch / session-open) and are still BLOCKED by the guard (live
+ * lane-state) whether or not this daemon is up. The check is therefore
+ * informational (never fails doctor); the verdict only drives the human-readable
+ * detail and whether `--fix` offers a relaunch.
+ *   - alive  — heartbeat fresh (age ≤ staleSec).
+ *   - wedged — stale heartbeat but the pidfile owner is STILL ALIVE: a live process
+ *              that has stopped stamping (the one genuinely odd state).
+ *   - idle   — stale/absent heartbeat and no live watcher: simply not running.
+ */
+function assessWatchHealth(args) {
+    const { ageSec, staleSec, hasLiveWatcher } = args;
+    if (ageSec != null && ageSec <= staleSec)
+        return 'alive';
+    if (hasLiveWatcher)
+        return 'wedged';
+    return 'idle';
+}
+/** The `doctor` "watch" detail line for a health state (age in seconds, or null). */
+function watchDetail(state, age) {
+    switch (state) {
+        case 'alive':
+            return `halt watcher alive (heartbeat ${age}s ago)`;
+        case 'wedged':
+            return `halt watcher process up but not heartbeating (${age}s) — restart the session if mid-turn halt pings stop`;
+        case 'idle':
+        default:
+            return 'halt watcher not running — relaunches at next session start (directed halts still surface via the pull path + the guard; `convene doctor --fix` starts one now)';
+    }
+}
 function readStdin() {
     try {
         return node_fs_1.default.readFileSync(0, 'utf8').trim();
@@ -450,33 +486,54 @@ async function doctor(opts) {
     // 6b. settings non-destructiveness — Convene's edits stay additive + marker-scoped;
     //     user-owned hooks/files are never clobbered. Fails only on genuine corruption.
     checks.push(assessSettingsIntegrity(top));
-    // 7. watch heartbeat — a stale/absent heartbeat means the mid-task halt watcher
-    // is DOWN (so directed halts won't surface between turns). Only meaningful for a
-    // repo on the bus; --fix may (re)launch `convene watch` detached.
+    // 6c. coordination-hook drift — the committed project .claude/settings.json should
+    //     carry the canonical COORD_HOOKS set. The writer (`convene init`) and this
+    //     check share ONE source of truth (../hook), so a hook added to COORD_HOOKS
+    //     (e.g. PR #55's Stop `convene wrap`) can't silently go unwired in a repo
+    //     onboarded earlier. Verbs THIS binary lacks are skipped. ADVISORY (ok:true):
+    //     drift is a nudge, not a hard failure — it must not fail doctor fleet-wide.
+    if (proj?.slug && top) {
+        const projSettings = (0, hook_1.parseSettings)((0, hook_1.readSettingsRaw)((0, hook_1.projectSettingsPath)(top)));
+        if (projSettings != null) {
+            const missing = (0, hook_1.missingCoordHooks)(projSettings);
+            checks.push({
+                name: 'coord-hooks',
+                ok: true,
+                detail: missing.length === 0
+                    ? 'committed coordination hooks match the canonical set'
+                    : `drifted — committed settings missing ${missing
+                        .map((h) => `${h.event} \`${h.command}\``)
+                        .join(', ')}; run \`convene init --refresh-docs\` to wire`,
+            });
+        }
+    }
+    // 7. watch heartbeat — the mid-task halt watcher is a BEST-EFFORT liveness/notify
+    // daemon that self-exits when its session goes idle and only relaunches at the
+    // next SessionStart, so a stale/absent heartbeat is EXPECTED for a quiet or
+    // long-lived session — NOT a failure. Directed halts surface via the pull path
+    // and are blocked by the guard regardless of this daemon. Informational only
+    // (never fails doctor); --fix offers a best-effort relaunch. See assessWatchHealth.
     if (proj?.slug) {
-        let age = (0, cache_1.watchHeartbeatAgeSec)(proj.slug);
-        let watchOk = age != null && age <= WATCH_STALE_SEC;
-        if (!watchOk && opts.fix) {
-            if (relaunchWatch(proj.slug)) {
+        const slug = proj.slug;
+        const watcherAlive = () => {
+            const p = (0, cache_1.readWatchPid)(slug);
+            return !!(p && (0, cache_1.isPidAlive)(p.pid));
+        };
+        let age = (0, cache_1.watchHeartbeatAgeSec)(slug);
+        let state = assessWatchHealth({ ageSec: age, staleSec: WATCH_STALE_SEC, hasLiveWatcher: watcherAlive() });
+        if (state !== 'alive' && opts.fix) {
+            if (relaunchWatch(slug)) {
                 // Give the freshly-launched daemon a beat to stamp its first heartbeat.
                 const until = Date.now() + 2500;
                 while (Date.now() < until) {
-                    age = (0, cache_1.watchHeartbeatAgeSec)(proj.slug);
+                    age = (0, cache_1.watchHeartbeatAgeSec)(slug);
                     if (age != null && age <= WATCH_STALE_SEC)
                         break;
                 }
-                watchOk = age != null && age <= WATCH_STALE_SEC;
+                state = assessWatchHealth({ ageSec: age, staleSec: WATCH_STALE_SEC, hasLiveWatcher: watcherAlive() });
             }
         }
-        checks.push({
-            name: 'watch',
-            ok: watchOk,
-            detail: watchOk
-                ? `halt watcher alive (heartbeat ${age}s ago)`
-                : age == null
-                    ? 'halt watcher DOWN — no heartbeat (run `convene doctor --fix` to relaunch)'
-                    : `halt watcher STALE — heartbeat ${age}s ago (run \`convene doctor --fix\` to relaunch)`,
-        });
+        checks.push({ name: 'watch', ok: true, detail: watchDetail(state, age) });
         // 7a. reap orphaned watchers — the cleanup half of the daemon-leak fix. Only
         // under --fix (running `ps` on every doctor would slow the fast path). Runs
         // AFTER the relaunch + heartbeat-wait above so the freshly-relaunched watcher

package/dist/commands/enroll.js

@@ -0,0 +1,72 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.enrollDevice = enrollDevice;
+/**
+ * `convene enroll-device` — connect THIS machine to your EXISTING identity without
+ * copying a key. Proves email ownership (an emailed confirm link) + device ownership
+ * (a CLI-held secret), then the server mints a fresh per-device key that ONLY this
+ * CLI can claim. Also auto-invoked by `convene setup`/`join` when the bus reports an
+ * identity already exists for your email (EMAIL_TAKEN).
+ */
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_os_1 = __importDefault(require("node:os"));
+const api_1 = require("../api");
+const config_1 = require("../config");
+const git_1 = require("../git");
+const ctx_1 = require("../ctx");
+const log = (m) => process.stdout.write(m + '\n');
+const sha256 = (s) => node_crypto_1.default.createHash('sha256').update(s, 'utf8').digest('hex');
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Run the device-enrollment flow. Returns true once a fresh key is saved to the
+ * local config; on timeout / expiry it prints guidance and exits the process.
+ */
+async function enrollDevice(opts) {
+    const top = (0, git_1.gitToplevel)();
+    const proj = (0, config_1.loadProjectConfig)(top);
+    const cfg = (0, config_1.resolveConfigForRepo)(top, proj);
+    const baseUrl = (opts.baseUrl || cfg.baseUrl).replace(/\/$/, '');
+    const email = opts.email || (0, git_1.gitUserEmail)(top ?? undefined) || undefined;
+    if (!email)
+        (0, ctx_1.die)('no email to enroll — pass `--email <you@example.com>` (or set git user.email)');
+    // CLI-held secret: send only its hash to start; present the raw secret at poll so
+    // ONLY this process can claim the minted key (a browser that clicks the link cannot).
+    const rawSecret = node_crypto_1.default.randomBytes(32).toString('base64url');
+    const secretHash = sha256(rawSecret);
+    const label = (opts.label || node_os_1.default.hostname() || 'cli').slice(0, 80);
+    const api = new api_1.ConveneApi(baseUrl, null);
+    const start = await api.enrollStart({ email: email, secret_hash: secretHash, device_label: label }, 10_000);
+    if (!start.ok || !start.json) {
+        (0, ctx_1.die)(`could not start device enrollment (${start.status}): ${start.error ?? 'unreachable'}`);
+    }
+    const { enrollment_id, poll_interval_ms, expires_in_s } = start.json;
+    const ttlS = expires_in_s ?? 900;
+    const mins = Math.max(1, Math.round(ttlS / 60));
+    log('');
+    log(`📧  We emailed a confirmation link to ${email}.`);
+    log(`    Open it and click "Authorize device" to connect this machine (expires in ${mins} min).`);
+    log(`    Waiting…`);
+    const intervalMs = Math.max(1000, poll_interval_ms ?? 2000);
+    const deadline = Date.now() + ttlS * 1000;
+    while (Date.now() < deadline) {
+        await sleep(intervalMs);
+        const poll = await api.enrollPoll(enrollment_id, rawSecret, 8000);
+        const st = poll.json?.status;
+        if (st === 'ok' && poll.json?.api_key) {
+            const member = poll.json.member?.handle ?? '';
+            (0, config_1.saveFileConfig)({ apiKey: poll.json.api_key, baseUrl, member });
+            log('');
+            log(`✓  Authorized as ${member}. This machine is connected (config saved 0600).`);
+            return true;
+        }
+        if (st === 'expired') {
+            (0, ctx_1.die)('the confirmation link expired or was already used — run `convene setup` again to retry.');
+        }
+        // 'pending' / 'not_found' → the human hasn't confirmed yet; keep waiting.
+    }
+    (0, ctx_1.die)('timed out waiting for email confirmation — run `convene setup` again to retry.');
+    return false; // unreachable: die() exits.
+}

package/dist/commands/explain.js

@@ -11,6 +11,7 @@ exports.explain = explain;
  * offline agent still gets the essentials. The endpoint is unauthenticated, so
  * this works even before `convene login`.
  */
+const node_child_process_1 = require("node:child_process");
 const config_1 = require("../config");
 const api_1 = require("../api");
 const brand_1 = require("../brand");
@@ -45,6 +46,20 @@ async function explain(question) {
             return;
         }
         if (res.ok && res.json && res.json.matched === false) {
+            // The agent asked how something works and Convene had no curated answer —
+            // the cleanest in-session friction signal. Capture it fire-and-forget
+            // (detached + unref'd, exactly as `convene fetch` spawns `convene announce`)
+            // so the product learns from confusion automatically instead of relying on a
+            // voluntary `convene suggest`. Gated on creds: no key/member → no spawn.
+            if (q && cfg.apiKey && cfg.member) {
+                try {
+                    const child = (0, node_child_process_1.spawn)(process.execPath, [process.argv[1], 'friction', '--kind', 'unmatched-explain', '--q', q], { detached: true, stdio: 'ignore' });
+                    child.unref();
+                }
+                catch {
+                    /* fail-open: friction capture must never break `explain` */
+                }
+            }
             // Unmatched query — point at the index + bundled essentials (still exit 0).
             process.stdout.write(`No specific match for "${q}". ${brand_1.BRAND.product} basics:\n\n${bundledSummary(cfg.baseUrl)}\n`);
             return;

package/dist/commands/friction.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.friction = friction;
+/**
+ * `convene friction` — automatic in-session CONFUSION capture. Files ONE
+ * low-severity feature_feedback row (category 'friction') when an agent hits a
+ * product rough edge the platform should learn from — today: an unmatched
+ * `convene explain` query (the agent literally asked how something works and
+ * Convene had no curated answer — the cleanest possible friction signal). It is
+ * spawned fire-and-forget by the surface that detects the friction (exactly as
+ * `convene fetch` spawns `convene announce`), so it NEVER blocks that surface.
+ *
+ * Mirrors `convene announce`'s posture:
+ *  - FAIL-OPEN: any error / missing config / non-bus repo exits 0 silently; a 5s
+ *    watchdog backstops a hang. It can never break the command that spawned it.
+ *  - IDEMPOTENT: a deterministic server idempotency-key
+ *    (`friction:<slug>:<instance>:<sigHash>`) is the authoritative dedupe; a local
+ *    (instance, sigHash) sentinel spares the redundant post when the SAME signal
+ *    recurs in a session.
+ *  - PRIVACY: the captured text is the agent's own words about Convene-the-product
+ *    — the same class of text `convene suggest` already mirrors to maintainers. It
+ *    is CLIPPED and posted only behind a valid key + project membership (the
+ *    authenticated-session gate). It never carries prompt text or work content
+ *    beyond the question the agent typed.
+ */
+const node_crypto_1 = require("node:crypto");
+const git_1 = require("../git");
+const config_1 = require("../config");
+const cache_1 = require("../cache");
+const api_1 = require("../api");
+const exit_1 = require("../exit");
+const SIGNAL_MAX = 240;
+function clip(s, max) {
+    const t = s.trim();
+    return t.length <= max ? t : t.slice(0, max - 1) + '…';
+}
+/** Stable short hash of the normalized signal — keys both the idempotency key and the local sentinel. */
+function signalHash(kind, signal) {
+    const norm = `${kind}\n${signal.toLowerCase().replace(/\s+/g, ' ').trim()}`;
+    return (0, node_crypto_1.createHash)('sha256').update(norm).digest('hex').slice(0, 16);
+}
+/** Human-readable feedback body for a friction kind. */
+function bodyFor(kind, signal) {
+    const q = clip(signal, SIGNAL_MAX);
+    switch (kind) {
+        case 'unmatched-explain':
+            return `Unmatched \`convene explain\` query (no curated answer): "${q}"`;
+        default:
+            return `[${kind}] ${q}`;
+    }
+}
+async function run(opts) {
+    const kind = (opts.kind ?? '').trim();
+    const signal = (opts.q ?? '').trim();
+    if (!kind || !signal)
+        return; // no signal → nothing to capture
+    const top = (0, git_1.gitToplevel)();
+    if (!top)
+        return; // not a git repo → silent no-op
+    const slug = opts.project || (0, config_1.loadProjectConfig)(top)?.slug || null;
+    if (!slug)
+        return; // repo not on the bus → silent no-op
+    const instance = (0, cache_1.ensureSessionInstance)(slug);
+    const sig = signalHash(kind, signal);
+    const body = bodyFor(kind, signal);
+    if (opts.dryRun) {
+        process.stdout.write(body + '\n');
+        return;
+    }
+    // Already captured this exact signal this session — spare the redundant post.
+    if ((0, cache_1.frictionAlreadyPosted)(slug, instance, sig))
+        return;
+    // The authenticated-session gate: only post with a real key + member.
+    const cfg = (0, config_1.resolveConfig)();
+    if (!cfg.apiKey || !cfg.member)
+        return;
+    const session = (0, git_1.sessionId)(cfg.member, top);
+    const api = new api_1.ConveneApi(cfg.baseUrl, cfg.apiKey, session, cfg.tool, instance);
+    const idem = `friction:${slug}:${instance}:${sig}`;
+    const res = await api.post(slug, { type: 'feature_feedback', body, category: 'friction', severity: 'low', tags: [kind] }, idem, 4000);
+    if (res.ok) {
+        // Only mark on success so a transient failure retries on the next occurrence.
+        (0, cache_1.markFrictionPosted)(slug, instance, sig);
+        if (res.json?.message?.short_id) {
+            process.stdout.write(`convene: captured [FRICTION] ${res.json.message.short_id} (${kind})\n`);
+        }
+    }
+}
+async function friction(opts = {}) {
+    // Backstop: force-exit on every path so a keep-alive socket can't linger.
+    const watchdog = setTimeout(() => (0, exit_1.exitClean)(0), 5000);
+    watchdog.unref();
+    const done = () => {
+        clearTimeout(watchdog);
+        (0, exit_1.exitClean)(0);
+    };
+    try {
+        await run(opts);
+    }
+    catch {
+        /* fail-open: a friction capture must never break the surface that spawned it */
+    }
+    done();
+}

package/dist/commands/init.js

@@ -223,72 +223,9 @@ function registerHook(noHook) {
         log(hookSnippet());
     }
 }
-/**
- * The WP13 coordination hooks, in INSTALL ORDER. Order matters for the two Bash
- * PreToolUse entries: `gate-push --stdin` is wired before `guard`, so `guard` lands
- * LAST among Bash PreToolUse hooks (awareness/ux #10) — the deploy gate runs, then
- * the cheap halt/lane backstop. Each entry names the VERB its binary must support;
- * a stale `convene` missing the verb is skipped (so it can't error on every boot).
- *
- * `convene watch` is NOT a Bash hook — it's a long-running detached daemon that
- * `convene session-start` spawns from the SessionStart path (§4.4). Wiring it as a
- * blocking Bash/PreToolUse entry would stall; launching from session-start keeps it
- * off the discretionary tool path.
- */
-const COORD_HOOKS = [
-    {
-        event: 'SessionStart',
-        matcher: 'startup|resume|clear',
-        command: 'convene session-start',
-        verb: 'session-start',
-        note: 'auto catch-up digest + mints the session-instance + launches `convene watch`',
-    },
-    {
-        event: 'PreToolUse',
-        matcher: 'Bash',
-        command: 'convene gate-push --stdin',
-        verb: 'gate-push',
-        note: 'deploy gate before a push (fail-open-loud)',
-    },
-    // guard is appended AFTER gate-push so it is LAST among Bash PreToolUse hooks.
-    {
-        event: 'PreToolUse',
-        matcher: 'Bash',
-        command: 'convene guard',
-        verb: 'guard',
-        note: 'halt + lane backstop for Bash (fail-open-loud)',
-    },
-    {
-        event: 'PreToolUse',
-        matcher: '.*',
-        command: 'convene guard --halt-only',
-        verb: 'guard',
-        note: 'cheap directed-halt backstop on every tool call',
-    },
-    {
-        event: 'PostToolUse',
-        matcher: 'Bash',
-        command: 'convene gate-push --post',
-        verb: 'gate-push',
-        note: 'release the deploy lane after a push (idempotent)',
-    },
-    {
-        event: 'PostToolUse',
-        matcher: 'Edit|Write|MultiEdit',
-        command: 'convene beat --stdin',
-        verb: 'beat',
-        note: 'debounced session activity-beat so a heads-down session still pulses on the bus',
-    },
-    // Stop fires at every turn-end (no tool matcher); `convene wrap` is idempotent +
-    // debounced via the last-broadcast-sha cursor, so it posts at most one wrap per
-    // stretch of new committed work and stays silent on idle turns. Never blocks.
-    {
-        event: 'Stop',
-        command: 'convene wrap',
-        verb: 'wrap',
-        note: 'session-end wrap status when new committed work landed (idempotent, fail-open)',
-    },
-];
+// COORD_HOOKS (the canonical coordination-hook set, in install order) + the
+// missingCoordHooks drift-check now live in ../hook as the SINGLE source of truth,
+// so the writer here and the `convene doctor` drift-check can never disagree.
 /**
  * Wire the WP13 coordination hooks into a settings file (global or committed
  * project), idempotent + merge-safe via ensureHook (deep-clone, never clobber,
@@ -297,7 +234,7 @@ const COORD_HOOKS = [
  */
 function registerCoordinationHooks(settingsPath, label) {
     let unparseable = false;
-    for (const h of COORD_HOOKS) {
+    for (const h of hook_1.COORD_HOOKS) {
         if (!(0, hook_1.binarySupportsVerb)(h.verb)) {
             log(`· ${label}: skipped \`${h.command}\` — installed \`convene\` lacks \`${h.verb}\` (upgrade the CLI to enable).`);
             continue;

package/dist/commands/join.js

@@ -15,6 +15,7 @@ const config_1 = require("../config");
 const git_1 = require("../git");
 const hook_1 = require("../hook");
 const githook_1 = require("../githook");
+const enroll_1 = require("./enroll");
 const ctx_1 = require("../ctx");
 const log = (m) => process.stdout.write(m + '\n');
 async function join(opts) {
@@ -34,8 +35,25 @@ async function join(opts) {
     // unauthenticated mode otherwise (creates a new identity + key).
     const api = new api_1.ConveneApi(baseUrl, cfg.apiKey ?? null);
     const res = await api.join(slug, { token, handle, email, display_name: handle, tool: 'cli' }, 10_000);
-    if (res.status === 409)
-        (0, ctx_1.die)(`the handle "${handle}" is already taken — re-run with --handle <unique-handle>`);
+    if (res.status === 409) {
+        const code = res.json?.code;
+        const keyHint = `paste your key (Settings → API key at ${brand_1.BRAND.siteUrl}/settings, or ~/.convene/config.json on your other machine)`;
+        if (code === 'EMAIL_TAKEN') {
+            // Same human, new machine: connect THIS machine to the existing identity with NO key
+            // copying — prove email ownership via an emailed link, then re-run join authenticated
+            // so the (now-known) member is added to this project (idempotent if already a member).
+            log(`An identity already exists for ${email ?? 'your email'} — connecting this machine to it (no key copying needed).`);
+            const ok = await (0, enroll_1.enrollDevice)({ email, baseUrl });
+            if (ok)
+                return join(opts);
+            return; // enrollDevice prints guidance + exits on failure
+        }
+        (0, ctx_1.die)(`The handle "${handle}" is already taken on this bus.\n` +
+            `If that's you (same person, another machine), connect to your existing identity:\n` +
+            `  convene login --api-key -    # ${keyHint}\n` +
+            `If you want a SEPARATE identity here, pick a different handle via your email:\n` +
+            `  convene setup --email <a-different-email>   # the handle is derived from the email's local part`);
+    }
     if (res.status === 401 && cfg.apiKey)
         (0, ctx_1.die)('join token is invalid/expired/revoked, or your saved key is bad — ask an owner');
     if (res.status === 401)