@manyoars/oars 0.4.1 → 0.5.1

package/dist/sessions/candidates.js

@@ -0,0 +1,236 @@
+// What a session could have loaded, recorded when it starts. A transcript holds the files the harness loaded, never the files that existed, and a working folder is often gone by
+// the time anyone asks, so a later read cannot tell a file the harness missed from a file that was never there. The session-start hook writes this snapshot to `candidates.jsonl`.
+//
+// Kinds and counts only: no path, file name, skill name, or file content enters a record. The two levels are how many folders up the repo root and the main checkout sit, which is
+// what lets a loaded file's own level be placed in a position later. Three more instruction-file kinds are counted in the working folder alone, the only place they were measured. The log is append-only and apart from `observations.jsonl`, because a snapshot cannot be captured again from
+// a transcript the way a capture record can, and it never reaches a pool batch.
+import { mkdir, readdir, readFile, stat } from 'node:fs/promises';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { HOOK_HARNESS } from '../telemetry/fields.js';
+import { appendOwnerOnly } from './owner-only.js';
+export const CANDIDATES_FILE = 'candidates.jsonl';
+export const CANDIDATE_RECORD_VERSION = 2;
+/** Where an instruction file sits relative to the session. `mainCheckout` is the span between a linked worktree and the main checkout that holds it, a span the harnesses treat apart. */
+export const INSTRUCTION_POSITIONS = ['working', 'parent', 'above', 'mainCheckout', 'user'];
+/** Claude Code's hook events, the 33 in the installed harness's own list (2.1.319). A name not on this list is counted as `other`, so a settings file cannot put free text in a record. */
+export const HOOK_EVENT_NAMES = [
+    'PreToolUse', 'PostToolUse', 'PostToolUseFailure', 'PermissionRequest', 'PermissionDenied', 'Notification', 'UserPromptSubmit', 'SessionStart', 'SessionEnd', 'Stop', 'StopFailure',
+    'SubagentStart', 'SubagentStop', 'TaskCreated', 'TaskCompleted', 'TeammateIdle', 'InstructionsLoaded', 'ConfigChange', 'CwdChanged', 'FileChanged', 'WorktreeCreate', 'WorktreeRemove',
+    'PreCompact', 'PostCompact', 'Elicitation', 'ElicitationResult', 'Setup',
+    'PostToolBatch', 'UserPromptExpansion', 'PreModelSwitch', 'PostModelSwitch', 'DirectoryAdded', 'MessageDisplay',
+];
+/** Instruction files beside `CLAUDE.md`, counted in the working folder only: `CLAUDE.local.md`, `.claude/CLAUDE.md`, and the `.claude/rules/` files that name no `paths` condition. */
+export const WORKING_KINDS = ['local', 'dotClaude', 'rules'];
+/** Where a settings file sits: the user's, the working folder's own `.claude/`, or a folder above it up to the repo root (and the main checkout root of a linked worktree). */
+export const HOOK_SOURCES = ['user', 'working', 'ancestors'];
+const INSTRUCTION_FILE = 'CLAUDE.md';
+const LOCAL_FILE = 'CLAUDE.local.md';
+const SKILL_FILE = 'SKILL.md';
+const EVENT_NAMES = new Set(HOOK_EVENT_NAMES);
+const isEventName = (name) => EVENT_NAMES.has(name);
+const isObject = (value) => typeof value === 'object' && value !== null;
+const isMissing = (error) => {
+    const code = isObject(error) ? Reflect.get(error, 'code') : undefined;
+    return code === 'ENOENT' || code === 'ENOTDIR';
+};
+/** A path's stat, undefined when nothing is there. Any other failure is thrown: a snapshot that could not look is not one that found nothing. */
+const statOf = async (path) => {
+    try {
+        return await stat(path);
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw error;
+    }
+};
+const isFile = async (path) => (await statOf(path))?.isFile() === true;
+const samePath = (a, b) => relative(a, b) === '';
+/** The folder and each of its parents, nearest first. */
+const chainOf = (dir) => {
+    const chain = [dir];
+    for (let up = dirname(dir); up !== chain[chain.length - 1]; up = dirname(up))
+        chain.push(up);
+    return chain;
+};
+/** The main checkout a linked worktree's `.git` pointer names; undefined for any other pointer (a submodule's). */
+const mainCheckoutOf = (pointer, dir) => {
+    const target = /^gitdir:\s*(.+?)\s*$/m.exec(pointer)?.[1];
+    if (target === undefined)
+        return undefined;
+    const gitDir = resolve(dir, target);
+    if (basename(dirname(gitDir)) !== 'worktrees')
+        return undefined;
+    const common = dirname(dirname(gitDir));
+    return basename(common) === '.git' ? dirname(common) : undefined;
+};
+const levelsOf = async (chain) => {
+    for (const [level, dir] of chain.entries()) {
+        const git = await statOf(join(dir, '.git'));
+        if (git === undefined)
+            continue;
+        if (git.isDirectory())
+            return { repoLevels: level, mainLevels: null };
+        const main = mainCheckoutOf(await readFile(join(dir, '.git'), 'utf8'), dir);
+        const mainLevel = main === undefined ? -1 : chain.findIndex((folder) => samePath(folder, main));
+        return { repoLevels: level, mainLevels: mainLevel > level ? mainLevel : null };
+    }
+    return { repoLevels: null, mainLevels: null };
+};
+/** Which position a folder `level` steps above the working folder holds; the derivation places a loaded file's level with this same rule. */
+export const positionOfLevel = (level, { repoLevels, mainLevels }) => {
+    if (level === 0)
+        return 'working';
+    if (repoLevels !== null && level <= repoLevels)
+        return 'parent';
+    if (mainLevels !== null && level <= mainLevels)
+        return 'mainCheckout';
+    return 'above';
+};
+const skillCount = async (skillsDir) => {
+    let names;
+    try {
+        names = await readdir(skillsDir);
+    }
+    catch (error) {
+        if (isMissing(error))
+            return 0;
+        throw error;
+    }
+    const found = await Promise.all(names.map((name) => isFile(join(skillsDir, name, SKILL_FILE))));
+    return found.filter(Boolean).length;
+};
+/** A rule file whose front matter carries a `paths` key loads only when a matching file is read; the measurement covered the ones without it. */
+const declaresPaths = (text) => {
+    const front = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text)?.[1];
+    return front?.split(/\r?\n/).some((line) => /^paths\s*:/.test(line)) === true;
+};
+/** How many `.md` files sit directly in a rules folder and name no `paths` condition. */
+const unconditionalRules = async (rulesDir) => {
+    let names;
+    try {
+        names = await readdir(rulesDir);
+    }
+    catch (error) {
+        if (isMissing(error))
+            return 0;
+        throw error;
+    }
+    const files = names.filter((name) => name.toLowerCase().endsWith('.md'));
+    const unconditional = await Promise.all(files.map(async (name) => ((await isFile(join(rulesDir, name))) ? !declaresPaths(await readFile(join(rulesDir, name), 'utf8')) : false)));
+    return unconditional.filter(Boolean).length;
+};
+const addHookCounts = async (file, counts) => {
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (isMissing(error))
+            return;
+        throw error;
+    }
+    const parsed = JSON.parse(text);
+    const hooks = isObject(parsed) ? Reflect.get(parsed, 'hooks') : undefined;
+    if (!isObject(hooks))
+        return;
+    for (const [event, groups] of Object.entries(hooks)) {
+        if (!Array.isArray(groups))
+            continue;
+        const commands = groups.reduce((sum, group) => {
+            const list = isObject(group) ? Reflect.get(group, 'hooks') : undefined;
+            return sum + (Array.isArray(list) ? list.length : 0);
+        }, 0);
+        if (commands === 0)
+            continue;
+        const name = isEventName(event) ? event : 'other';
+        counts[name] = (counts[name] ?? 0) + commands;
+    }
+};
+const addSettingsHooks = async (dir, counts) => {
+    await addHookCounts(join(dir, '.claude', 'settings.json'), counts);
+    await addHookCounts(join(dir, '.claude', 'settings.local.json'), counts);
+};
+/** Counts what exists around `cwd`, under the harness's config folder `claudeDir`. It throws on anything but a missing file. */
+export const snapshotCandidates = async ({ cwd, claudeDir }) => {
+    const chain = chainOf(cwd);
+    const levels = await levelsOf(chain);
+    // A session inside the config folder climbs through it: the file there is the user-level one, counted once below.
+    const isConfigFolder = (dir) => samePath(dir, claudeDir);
+    const isConfigParent = (dir) => samePath(join(dir, '.claude'), claudeDir);
+    const instructions = { working: 0, parent: 0, above: 0, mainCheckout: 0, user: (await isFile(join(claudeDir, INSTRUCTION_FILE))) ? 1 : 0 };
+    for (const [level, dir] of chain.entries()) {
+        if (!isConfigFolder(dir) && (await isFile(join(dir, INSTRUCTION_FILE))))
+            instructions[positionOfLevel(level, levels)] += 1;
+    }
+    // The working folder holds the config folder when the session runs in the home folder: its `.claude/` files are the user's, already counted.
+    const workingKinds = { local: (await isFile(join(cwd, LOCAL_FILE))) ? 1 : 0, dotClaude: 0, rules: 0 };
+    if (!isConfigParent(cwd)) {
+        workingKinds.dotClaude = (await isFile(join(cwd, '.claude', INSTRUCTION_FILE))) ? 1 : 0;
+        workingKinds.rules = await unconditionalRules(join(cwd, '.claude', 'rules'));
+    }
+    // Skills load from every folder up to the repo root, and from the main checkout root when the session runs in a linked worktree.
+    const mainRoot = levels.mainLevels === null ? [] : [chain[levels.mainLevels] ?? cwd];
+    const projectFolders = [...chain.slice(0, (levels.repoLevels ?? 0) + 1), ...mainRoot].filter((dir) => !isConfigParent(dir));
+    const skills = { project: 0, user: await skillCount(join(claudeDir, 'skills')) };
+    for (const dir of projectFolders)
+        skills.project += await skillCount(join(dir, '.claude', 'skills'));
+    // Settings load from the user's folder and the working folder's own `.claude/`; a folder above it is skipped by design but still counted, so the skip can be told from absence.
+    const hooks = { user: {}, working: {}, ancestors: {} };
+    await addHookCounts(join(claudeDir, 'settings.json'), hooks.user);
+    const aboveFolders = chain.slice(1, (levels.repoLevels ?? 0) + 1);
+    for (const dir of [...aboveFolders, ...mainRoot]) {
+        if (!isConfigParent(dir))
+            await addSettingsHooks(dir, hooks.ancestors);
+    }
+    if (!isConfigParent(cwd))
+        await addSettingsHooks(cwd, hooks.working);
+    return { instructions, workingKinds, skills, hooks, ...levels };
+};
+/**
+ * Appends this session's snapshot. Fail-open: any error writes nothing and returns, because a hook must never fail or block a session, and a partial count would read as evidence
+ * that files were absent. The counts are finished before the store is touched, so nothing partial can reach the file.
+ */
+export const recordCandidates = async (storeDir, { session, cwd, claudeDir, at }) => {
+    try {
+        const counts = await snapshotCandidates({ cwd, claudeDir });
+        const record = { v: CANDIDATE_RECORD_VERSION, session, at, harness: HOOK_HARNESS, ...counts };
+        await mkdir(storeDir, { recursive: true });
+        await appendOwnerOnly(join(storeDir, CANDIDATES_FILE), `${JSON.stringify(record)}\n`);
+    }
+    catch {
+        // Fail-open, as above.
+    }
+};
+/** A line of this version with its four count groups: one without them (hand-edited, or written badly) would throw in the join, outside its guard. */
+const isSnapshot = (value) => isObject(value) &&
+    Reflect.get(value, 'v') === CANDIDATE_RECORD_VERSION &&
+    typeof Reflect.get(value, 'session') === 'string' &&
+    ['instructions', 'workingKinds', 'skills', 'hooks'].every((group) => isObject(Reflect.get(value, group)));
+const parsedLine = (line) => {
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+};
+/** The first snapshot of each session (a resumed session starts again and appends another), by session id. A line of another version or a torn line is skipped. */
+export const readCandidates = async (storeDir) => {
+    const snapshots = new Map();
+    let text;
+    try {
+        text = await readFile(join(storeDir, CANDIDATES_FILE), 'utf8');
+    }
+    catch (error) {
+        if (isMissing(error))
+            return snapshots;
+        throw error;
+    }
+    for (const line of text.split('\n')) {
+        const parsed = parsedLine(line);
+        if (isSnapshot(parsed) && !snapshots.has(parsed.session))
+            snapshots.set(parsed.session, parsed);
+    }
+    return snapshots;
+};

package/dist/sessions/card-command.d.ts

@@ -0,0 +1,24 @@
+import type { Outcome } from '../cli.js';
+import { type CardPeriod } from './card.js';
+import type { SessionsDeps } from './command.js';
+export declare const ASHORE = "ashore: run oars pool login";
+/**
+ * The depositor row. Signed out it points at `oars pool login`; signed in it counts the weeks (Monday-start, UTC) in which this machine's sent record holds a deposit,
+ * labeled as this machine's because the record is local. It reads two local files and makes no network call; a sign-in file or pool address that cannot be read is
+ * signed out, since a share card must not fail on it.
+ */
+export declare const depositorLine: (storeDir: string, env: NodeJS.ProcessEnv, now: number) => Promise<string>;
+export interface CardOptions {
+    period: CardPeriod;
+    text: boolean;
+    /** A `.png` or `.svg` path: both pictures are written, with this name's extension swapped for each. */
+    out?: string | undefined;
+    /** Leave the cost row out of the picture, the table, and the JSON. */
+    noCost?: boolean | undefined;
+}
+/** The two paths a card is saved to: `--out` names the base, the default is one per period in the working directory. */
+export declare const cardPaths: (period: CardPeriod, out: string | undefined) => {
+    svg: string;
+    png: string;
+};
+export declare const sessionsCard: (deps: SessionsDeps, options: CardOptions, env: NodeJS.ProcessEnv) => Promise<Outcome>;

package/dist/sessions/card-command.js

@@ -0,0 +1,71 @@
+// `oars card`: reads the local store, prints the card as a table (`--text`) or saves it as an SVG and a PNG, and prints one prefilled x.com link. Nothing is
+// uploaded and no network call is made.
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { CliError, ExitCode } from '../errors.js';
+import { cardOf, cardText, tweetLink } from './card.js';
+import { cardPng, cardSvg } from './card-render.js';
+import { emptyBooks } from './empty-state.js';
+import { poolServer } from './pool-command.js';
+import { outboxFolder } from './pool-outbox.js';
+import { loadSignIns } from './pool-replica.js';
+import { sentLog } from './pool-sent.js';
+import { loadStore } from './store.js';
+import { readSurvival } from './survival.js';
+export const ASHORE = 'ashore: run oars pool login';
+const DAY = 86_400_000;
+const WEEK = 7 * DAY;
+/** 1970-01-01 was a Thursday, so this is the Monday before it: weeks counted from here start on a Monday, UTC. */
+const FIRST_MONDAY = -3 * DAY;
+/**
+ * The depositor row. Signed out it points at `oars pool login`; signed in it counts the weeks (Monday-start, UTC) in which this machine's sent record holds a deposit,
+ * labeled as this machine's because the record is local. It reads two local files and makes no network call; a sign-in file or pool address that cannot be read is
+ * signed out, since a share card must not fail on it.
+ */
+export const depositorLine = async (storeDir, env, now) => {
+    try {
+        const server = poolServer(env, 'card');
+        const signedIn = (await loadSignIns(storeDir, 'card')).some((entry) => entry.server === server && entry.expiresAt > now);
+        if (!signedIn)
+            return ASHORE;
+        const weeks = new Set();
+        for (const at of (await sentLog(outboxFolder(storeDir, server))).values()) {
+            const time = Date.parse(at);
+            if (!Number.isNaN(time))
+                weeks.add(Math.floor((time - FIRST_MONDAY) / WEEK));
+        }
+        return `weeks rowing (this machine): ${String(weeks.size)}`;
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            return ASHORE;
+        throw error;
+    }
+};
+/** The two paths a card is saved to: `--out` names the base, the default is one per period in the working directory. */
+export const cardPaths = (period, out) => {
+    if (out !== undefined && !/\.(?:png|svg)$/i.test(out))
+        throw new CliError(`--out ${out} must end in .png or .svg.`, ExitCode.USAGE, 'usage');
+    const base = resolve(out === undefined ? `oars-card-${period}` : out.replace(/\.(?:png|svg)$/i, ''));
+    return { svg: `${base}.svg`, png: `${base}.png` };
+};
+export const sessionsCard = async (deps, options, env) => {
+    if (deps.sessions === undefined)
+        throw new CliError('The session store is not configured in this run.', ExitCode.UNEXPECTED, 'unexpected');
+    const paths = cardPaths(options.period, options.out);
+    const store = await loadStore(deps.sessions.storeDir);
+    const card = cardOf(store, await readSurvival(deps.sessions.storeDir), options.period, deps.now(), options.noCost !== true);
+    const link = tweetLink(card);
+    if (card.sessions === 0) {
+        const empty = store.sessions.length === 0 && store.prompts.length === 0 ? emptyBooks('prompts') : `No sessions in the last ${String(card.days)} days in the local store.`;
+        return { document: { ok: true, card, saved: null, tweet: null }, text: empty };
+    }
+    const depositor = await depositorLine(deps.sessions.storeDir, env, deps.now());
+    if (options.text)
+        return { document: { ok: true, card, saved: null, tweet: link }, text: [cardText(card, depositor), '', link].join('\n') };
+    const svg = cardSvg(card, depositor);
+    await mkdir(dirname(paths.svg), { recursive: true });
+    await writeFile(paths.svg, svg);
+    await writeFile(paths.png, cardPng(svg));
+    return { document: { ok: true, card, saved: paths, tweet: link }, text: [`Saved ${paths.png}`, `Saved ${paths.svg}`, 'Nothing was uploaded: the card was made from your local store.', '', `Post it (add the picture yourself): ${link}`].join('\n') };
+};

package/dist/sessions/card-font.d.ts

@@ -0,0 +1,6 @@
+/** The glyphs from ASCII 32 on, each as five column bytes. */
+export declare const GLYPHS: readonly (readonly number[])[];
+export declare const GLYPH_WIDTH = 5;
+export declare const GLYPH_HEIGHT = 8;
+/** Whether the pixel at (column, row) of a character is lit; any character outside ASCII 32 to 126 draws as `?`. */
+export declare const lit: (char: string, column: number, row: number) => boolean;

package/dist/sessions/card-font.js

@@ -0,0 +1,36 @@
+// A 5x7 bitmap font for the card's PNG, so the picture needs no renderer dependency, no font file, and no system font. Each glyph is five column bytes
+// (ten hex digits), bit 0 the top row; bit 7 is the one descender row. ASCII 32 to 126 only: a model or harness name the card prints is always inside that range.
+const COLUMNS = [
+    // space ! " # $ % & ' ( ) * + , - . /
+    '0000000000', '00005f0000', '0007000700', '147f147f14', '242a7f2a12', '2313086462', '3649562050', '0008070300',
+    '001c224100', '0041221c00', '2a1c7f1c2a', '08083e0808', '0080703000', '0808080808', '0000606000', '2010080402',
+    // 0 to 9
+    '3e5149453e', '00427f4000', '7249494946', '2141494d33', '1814127f10', '2745454539', '3c4a494931', '4121110907',
+    '3649494936', '464949291e',
+    // : ; < = > ? @
+    '0000140000', '0040340000', '0008142241', '1414141414', '0041221408', '0201590906', '3e415d594e',
+    // A to Z
+    '7c1211127c', '7f49494936', '3e41414122', '7f4141413e', '7f49494941', '7f09090901', '3e41415173', '7f0808087f',
+    '00417f4100', '2040413f01', '7f08142241', '7f40404040', '7f021c027f', '7f0408107f', '3e4141413e', '7f09090906',
+    '3e4151215e', '7f09192946', '2649494932', '03017f0103', '3f4040403f', '1f2040201f', '3f4038403f', '6314081463',
+    '0304780403', '6159494d43',
+    // [ \ ] ^ _ `
+    '007f414141', '0204081020', '004141417f', '0402010204', '4040404040', '0003070800',
+    // a to z
+    '2054547840', '7f28444438', '3844444428', '384444287f', '3854545418', '00087e0902', '18a4a49c78', '7f08040478',
+    '00447d4000', '2040403d00', '7f10284400', '00417f4000', '7c04780478', '7c08040478', '3844444438', 'fc18242418',
+    '18242418fc', '7c08040408', '4854545424', '04043f4424', '3c40402078', '1c2040201c', '3c4030403c', '4428102844',
+    '4c9090907c', '4464544c44',
+    // { | } ~
+    '0008364100', '0000770000', '0041360800', '0201020402',
+];
+/** The glyphs from ASCII 32 on, each as five column bytes. */
+export const GLYPHS = COLUMNS.map((hex) => Array.from({ length: 5 }, (_, column) => Number.parseInt(hex.slice(column * 2, column * 2 + 2), 16)));
+export const GLYPH_WIDTH = 5;
+export const GLYPH_HEIGHT = 8;
+/** Whether the pixel at (column, row) of a character is lit; any character outside ASCII 32 to 126 draws as `?`. */
+export const lit = (char, column, row) => {
+    const code = char.charCodeAt(0);
+    const glyph = GLYPHS[code >= 32 && code <= 126 ? code - 32 : 31] ?? [];
+    return (((glyph[column] ?? 0) >> row) & 1) === 1;
+};

package/dist/sessions/card-line.d.ts

@@ -0,0 +1,30 @@
+import type { CardLineArm } from '../telemetry/schema.js';
+/** Out of 100 installs, this many never see the line. */
+export declare const HELD_PERCENT = 10;
+/** The ISO week (`2026-W45`) of a local date. The week's Thursday names its year. */
+export declare const isoWeekOf: (now: number) => string;
+/** Friday, Saturday, or Sunday local time: the ISO week's last three days, so a first command on or after Friday 00:00 is in the week it counts. */
+export declare const fridayOrLater: (now: number) => boolean;
+/** The week's text. Singular at one; nothing else (no install, star, or link words). */
+export declare const cardLineText: (sessions: number, strokes: number) => string;
+/** Stable per install: the first four bytes of a SHA-256 of the id, taken mod 100, under the holdback percent. */
+export declare const isHeld: (id: string) => boolean;
+export interface CardLineInput {
+    storeDir: string;
+    telemetryDir?: string | undefined;
+    now: number;
+    /** Whether stderr is a terminal: the line is for a person reading it. */
+    tty: boolean;
+    argv: readonly string[];
+    /** The command path and flag names the run observed. */
+    path: readonly string[];
+    flags: readonly string[];
+    stderr: (text: string) => void;
+}
+/** A hook, the MCP server, a recall, `sessions try`, `--json`, or `oars card` itself: the line never goes there. */
+export declare const quiet: (input: Pick<CardLineInput, "argv" | "path" | "flags">) => boolean;
+/**
+ * Decides and, when due, prints. A store that cannot be read writes the week's marker as `not_due`, so a failing store costs one command a week; a week with no
+ * session leaves the marker unwritten, so it is checked again on each due command and the line can still come later in the week. Returns the arm for the command event; any error reads `not_due`.
+ */
+export declare const cardLine: (input: CardLineInput) => Promise<CardLineArm>;

package/dist/sessions/card-line.js

@@ -0,0 +1,105 @@
+// The weekly line: once per ISO week, on the first command a person runs on or after Friday 00:00 local time, stderr gets one line pointing at `oars card --text`.
+// A stable tenth of installs never see it (the holdback), so the loop's effect can be read later. It is for people at a terminal only: never `--json`, a hook, the MCP
+// server, a recall, `oars sessions try`, or `oars card` itself. It makes no network call and never fails or delays a command: every error is swallowed.
+import { createHash, randomUUID } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isHook } from '../telemetry/observe.js';
+import { cardOf } from './card.js';
+import { mkdirOwnerOnly, writeOwnerOnly } from './owner-only.js';
+import { loadStore } from './store.js';
+import { readSurvival } from './survival.js';
+/** Out of 100 installs, this many never see the line. */
+export const HELD_PERCENT = 10;
+const MARKER = 'card-line.json';
+const ID_FILE = 'card-line-id';
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const FRIDAY = 5;
+/** The ISO week (`2026-W45`) of a local date. The week's Thursday names its year. */
+export const isoWeekOf = (now) => {
+    const date = new Date(now);
+    const thursday = new Date(date.getFullYear(), date.getMonth(), date.getDate() + 4 - (date.getDay() || 7), 12);
+    const first = new Date(thursday.getFullYear(), 0, 1, 12);
+    const week = Math.ceil((Math.round((thursday.getTime() - first.getTime()) / 86_400_000) + 1) / 7);
+    return `${String(thursday.getFullYear())}-W${String(week).padStart(2, '0')}`;
+};
+/** Friday, Saturday, or Sunday local time: the ISO week's last three days, so a first command on or after Friday 00:00 is in the week it counts. */
+export const fridayOrLater = (now) => {
+    const day = new Date(now).getDay();
+    return day === 0 || day >= FRIDAY;
+};
+/** The week's text. Singular at one; nothing else (no install, star, or link words). */
+export const cardLineText = (sessions, strokes) => `Your week: ${String(sessions)} ${sessions === 1 ? 'session' : 'sessions'}, ${String(strokes)} ${strokes === 1 ? 'stroke' : 'strokes'}. \`oars card --text\` for the table.\n`;
+const readTrimmed = async (file) => {
+    try {
+        return (await readFile(file, 'utf8')).trim();
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * This install's id for the holdback, frozen at the first decision so the arm never flips: the id file in the store folder when it exists; otherwise it is seeded from
+ * the telemetry install id when that file exists (never created here, so a person who turned telemetry off gets no new file), else a random value, and written.
+ */
+const holdbackId = async (storeDir, telemetryDir) => {
+    const own = await readTrimmed(join(storeDir, ID_FILE));
+    if (own !== undefined && UUID.test(own))
+        return own;
+    const shared = telemetryDir === undefined ? undefined : await readTrimmed(join(telemetryDir, 'install-id'));
+    const id = shared !== undefined && UUID.test(shared) ? shared : randomUUID();
+    await mkdirOwnerOnly(storeDir);
+    await writeOwnerOnly(join(storeDir, ID_FILE), `${id}\n`);
+    return id;
+};
+/** Stable per install: the first four bytes of a SHA-256 of the id, taken mod 100, under the holdback percent. */
+export const isHeld = (id) => createHash('sha256').update(`card-line:${id}`).digest().readUInt32BE(0) % 100 < HELD_PERCENT;
+/** A hook, the MCP server, a recall, `sessions try`, `--json`, or `oars card` itself: the line never goes there. */
+export const quiet = (input) => {
+    const { argv, path, flags } = input;
+    return path.length === 0 || path[0] === 'card' || path.includes('hook') || (path[0] === 'sessions' && (path[1] === 'recall' || path[1] === 'try')) || isHook([...argv], { path: [...path], flags: [...flags] }) || flags.includes('json') || flags.includes('mcp') || argv.includes('--json');
+};
+const markedWeek = async (storeDir) => {
+    const text = await readTrimmed(join(storeDir, MARKER));
+    if (text === undefined)
+        return undefined;
+    const parsed = JSON.parse(text);
+    const week = typeof parsed === 'object' && parsed !== null ? Reflect.get(parsed, 'week') : undefined;
+    return typeof week === 'string' ? week : undefined;
+};
+const mark = async (storeDir, week, arm) => {
+    await mkdirOwnerOnly(storeDir);
+    await writeOwnerOnly(join(storeDir, MARKER), `${JSON.stringify({ week, arm })}\n`);
+};
+/**
+ * Decides and, when due, prints. A store that cannot be read writes the week's marker as `not_due`, so a failing store costs one command a week; a week with no
+ * session leaves the marker unwritten, so it is checked again on each due command and the line can still come later in the week. Returns the arm for the command event; any error reads `not_due`.
+ */
+export const cardLine = async (input) => {
+    try {
+        if (!input.tty || quiet(input) || !fridayOrLater(input.now))
+            return 'not_due';
+        const week = isoWeekOf(input.now);
+        if ((await markedWeek(input.storeDir).catch(() => undefined)) === week)
+            return 'not_due';
+        let card;
+        try {
+            card = cardOf(await loadStore(input.storeDir), await readSurvival(input.storeDir), 'week', input.now);
+        }
+        catch {
+            await mark(input.storeDir, week, 'not_due');
+            return 'not_due';
+        }
+        if (card.sessions === 0)
+            return 'not_due';
+        const held = isHeld(await holdbackId(input.storeDir, input.telemetryDir));
+        const arm = held ? 'held' : 'shown';
+        await mark(input.storeDir, week, arm);
+        if (!held)
+            input.stderr(cardLineText(card.sessions, card.strokes));
+        return arm;
+    }
+    catch {
+        return 'not_due';
+    }
+};

package/dist/sessions/card-render.d.ts

@@ -0,0 +1,15 @@
+import { type Card } from './card.js';
+export declare const PITCH = 36;
+export declare const cardSvg: (card: Card, depositor: string) => string;
+export interface Raster {
+    width: number;
+    height: number;
+    /** 8-bit RGB, row by row. */
+    rgb: Buffer;
+}
+/** Pixels for the SVG `cardSvg` writes: rects and monospace text in document order, a text's font size a whole multiple of ten. */
+export declare const rasterize: (svg: string) => Raster;
+/** An 8-bit RGB PNG, unfiltered rows, zlib at level 9 (deterministic for one input). */
+export declare const encodePng: (width: number, height: number, rgb: Buffer) => Buffer;
+/** The PNG for an SVG `cardSvg` wrote. */
+export declare const cardPng: (svg: string) => Buffer;