@nonameolsson/nightjar 0.0.0-stage → 0.2.0

package/dist/workflow.js

@@ -0,0 +1,53 @@
+// A Feature's own `**Workflow:**` line, as written; the bold is optional.
+export function workflowLine(body) {
+    const match = /^(?:\*\*)?Workflow:(?:\*\*)?[ \t]*([^*\s].*?)\s*$/im.exec(body);
+    return match?.[1]?.replace(/^`(.*)`$/, '$1').trim() || undefined;
+}
+export function chooseWorkflow(settings, body) {
+    const known = Object.keys(settings.workflows ?? {});
+    const asked = workflowLine(body);
+    const name = asked === undefined
+        ? settings.defaultWorkflow
+        : (known.find((n) => n === asked) ??
+            known.find((n) => n.toLowerCase() === asked.toLowerCase()));
+    if (asked === undefined && name === undefined)
+        return { kind: 'none' };
+    const workflow = name === undefined ? undefined : settings.workflows?.[name];
+    if (name === undefined || workflow === undefined) {
+        const list = known.length === 0 ? 'factory.json names none' : known.map((n) => `\`${n}\``).join(', ');
+        return {
+            kind: 'refused',
+            why: `its \`**Workflow:**\` line names \`${asked ?? ''}\`, which is no Workflow. The Workflows known: ${list}.`
+        };
+    }
+    const broken = settings.brokenWorkflows?.[name];
+    if (broken !== undefined) {
+        return { kind: 'refused', why: `the Workflow \`${name}\` cannot run: ${broken}` };
+    }
+    return { kind: 'workflow', name, workflow };
+}
+// What a Step is called in a commit trailer, which tells a later run it is done.
+export const stepKey = (workflow, step, ticket) => `${workflow}/${step}${ticket === null ? '' : ` #${ticket}`}`;
+// The skills a Step's prompt names with a slash, such as `/some-skill args`.
+export function skillsNamed(prompt) {
+    const names = [
+        ...prompt.matchAll(/(?<![\w/.:~-])\/([a-z][a-z0-9_-]*(?::[a-z][a-z0-9_-]*)?)(?![\w/.-])/g)
+    ];
+    return [...new Set(names.flatMap((m) => (m[1] ? [m[1]] : [])))];
+}
+// The pull request's section on a Workflow, or null when it ran no Step.
+export function workflowSection(name, reports, ref) {
+    if (reports.length === 0)
+        return null;
+    const lines = reports.map((r) => {
+        const where = `\`${r.step.name}\`${r.ticket === null ? '' : ` (after ${ref(r.ticket)})`}`;
+        if (r.state === 'done')
+            return `- ${where}: done`;
+        if (r.state === 'undone')
+            return `- ${where}: **not done**, ${r.why ?? 'it did not finish'}; its changes were thrown away`;
+        const left = r.left.map((l) => `\n  - ${l}`).join('');
+        return `- ${where}: its condition (${r.step.until ?? ''}) did not hold after ${String(r.rounds ?? 0)} round${r.rounds === 1 ? '' : 's'}. Left:${left || ' (it listed nothing)'}`;
+    });
+    return `## Workflow \`${name}\`\n\n${lines.join('\n')}`;
+}
+//# sourceMappingURL=workflow.js.map

package/dist/workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow.js","sourceRoot":"","sources":["../src/workflow.ts"],"names":[],"mappings":"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"}

package/dist/worktree.d.ts

@@ -0,0 +1,44 @@
+import { type Env } from './git.js';
+export declare class GitFailure extends Error {
+}
+export declare const TICKET_TRAILER = "Factory-Ticket";
+export declare const STEP_TRAILER = "Factory-Step";
+export declare function branchFor(id: string, title: string): string;
+export declare function worktreesFor(home: string, root: string): string;
+export interface FeatureBranch {
+    readonly branch: string;
+    readonly folder: string;
+    readonly base: string;
+}
+export declare class Worktree {
+    readonly at: FeatureBranch;
+    private readonly env;
+    constructor(at: FeatureBranch, env: Env);
+    git(args: readonly string[]): Promise<string>;
+    private setupMarker;
+    isSetUp: () => Promise<boolean>;
+    markSetUp: () => Promise<void>;
+    head: () => Promise<string>;
+    ahead: () => Promise<number>;
+    built(): Promise<Set<string>>;
+    commitTicket(id: string, title: string, summary: string, session: string): Promise<boolean>;
+    notes(): Promise<string>;
+    stepsDone(): Promise<Set<string>>;
+    diff(limit: number): Promise<{
+        text: string;
+        truncated: boolean;
+    }>;
+    commitStep(o: {
+        workflow: string;
+        step: string;
+        key: string;
+        after: string | null;
+        summary: string;
+        session: string;
+    }): Promise<boolean>;
+    revert(before: string): Promise<void>;
+    discard(before: string, ticket: string): Promise<string | null>;
+}
+export declare function openWorktree(root: string, worktrees: string, branch: string, baseBranch: string, env: Env): Promise<Worktree>;
+export declare function defaultBranch(root: string, env: Env): Promise<string | null>;
+export declare function signing(root: string, env: Env): Promise<'signs' | 'unsigned' | 'fails'>;

package/dist/worktree.js

@@ -0,0 +1,193 @@
+// Only Nightjar commits in the worktree or saves a failed attempt; the Code host pushes.
+import { createHash } from 'node:crypto';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { firstLine, run } from './git.js';
+// A git command Nightjar cannot go on without.
+export class GitFailure extends Error {
+}
+// Names the Ticket a commit built, so a later run on the branch knows what is done.
+export const TICKET_TRAILER = 'Factory-Ticket';
+// Names the Workflow Step a commit holds, so a later run knows it is done.
+export const STEP_TRAILER = 'Factory-Step';
+// The notes the Steps of a run share, in the worktree and never committed.
+const NOTES = '.factory/notes';
+const BRANCH_PREFIX = 'factory/';
+// An item id as a piece of a branch name: whatever a ref may not hold becomes a dash.
+const refPart = (id) => id.replace(/[^A-Za-z0-9_-]+/g, '-');
+export function branchFor(id, title) {
+    const slug = title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 40)
+        .replace(/-+$/, '');
+    return `${BRANCH_PREFIX}${refPart(id)}${slug ? `-${slug}` : ''}`;
+}
+// Out of the checkout, so the one a person works in is never touched; the hash keeps two checkouts of one name apart.
+export function worktreesFor(home, root) {
+    const hash = createHash('sha256').update(root).digest('hex').slice(0, 8);
+    return join(home, '.nightjar', 'worktrees', `${basename(root)}-${hash}`);
+}
+export class Worktree {
+    at;
+    env;
+    constructor(at, env) {
+        this.at = at;
+        this.env = env;
+    }
+    async git(args) {
+        const got = await run('git', args, this.at.folder, this.env);
+        if (got.missing)
+            throw new GitFailure('git is not on the PATH.');
+        if (!got.ok)
+            throw new GitFailure(`git ${args[0] ?? ''} failed: ${firstLine(got.err)}`);
+        return got.out;
+    }
+    // In git's own folder for the worktree, so neither `git clean` nor a commit touches it.
+    async setupMarker() {
+        const path = (await this.git(['rev-parse', '--git-path', 'nightjar-setup'])).trim();
+        return resolve(this.at.folder, path);
+    }
+    isSetUp = async () => existsSync(await this.setupMarker());
+    markSetUp = async () => writeFileSync(await this.setupMarker(), '');
+    head = async () => (await this.git(['rev-parse', 'HEAD'])).trim();
+    ahead = async () => Number((await this.git(['rev-list', '--count', `${this.at.base}..HEAD`])).trim());
+    // The Tickets the branch's own commits built, from their trailers, oldest first.
+    async built() {
+        const out = await this.git([
+            'log',
+            '--reverse',
+            `--format=%(trailers:key=${TICKET_TRAILER},valueonly)`,
+            `${this.at.base}..HEAD`
+        ]);
+        return new Set([...out.matchAll(/^#(\S+)$/gm)].flatMap((m) => (m[1] ? [m[1]] : [])));
+    }
+    // One commit of everything the session left, or false when it left nothing.
+    async commitTicket(id, title, summary, session) {
+        await this.git(['add', '-A']);
+        if ((await this.git(['diff', '--cached', '--name-only'])).trim() === '')
+            return false;
+        const message = `${title} (#${id})\n\n${summary.trim()}\n\n${TICKET_TRAILER}: #${id}\nFactory-Session: ${session}`;
+        await this.git(['commit', '-q', '-m', message]);
+        return true;
+    }
+    // The folder the Steps share, made, and kept out of every `git add` and `git clean` by the checkout's exclude file.
+    async notes() {
+        const folder = join(this.at.folder, NOTES);
+        mkdirSync(folder, { recursive: true });
+        const path = (await this.git(['rev-parse', '--git-path', 'info/exclude'])).trim();
+        const exclude = resolve(this.at.folder, path);
+        const line = `/${NOTES}/`;
+        const text = existsSync(exclude) ? readFileSync(exclude, 'utf8') : '';
+        if (!text.split('\n').includes(line)) {
+            mkdirSync(dirname(exclude), { recursive: true });
+            appendFileSync(exclude, `${text === '' || text.endsWith('\n') ? '' : '\n'}${line}\n`);
+        }
+        return folder;
+    }
+    // The Steps the branch's own commits hold, as their trailers name them.
+    async stepsDone() {
+        const out = await this.git([
+            'log',
+            `--format=%(trailers:key=${STEP_TRAILER},valueonly)`,
+            `${this.at.base}..HEAD`
+        ]);
+        return new Set(out.split('\n').flatMap((l) => (l.trim() === '' ? [] : [l.trim()])));
+    }
+    // The Feature's diff against its base, cut at `limit` characters.
+    async diff(limit) {
+        const text = await this.git(['diff', `${this.at.base}...HEAD`]);
+        return text.length > limit
+            ? { text: text.slice(0, limit), truncated: true }
+            : { text, truncated: false };
+    }
+    // One commit of what a Step left, naming the Workflow and the Step; false when it changed no file.
+    async commitStep(o) {
+        await this.git(['add', '-A']);
+        if ((await this.git(['diff', '--cached', '--name-only'])).trim() === '')
+            return false;
+        const subject = `${o.workflow}: ${o.step}${o.after === null ? '' : ` (after #${o.after})`}`;
+        const message = `${subject}\n\n${o.summary.trim()}\n\n${STEP_TRAILER}: ${o.key}\nFactory-Session: ${o.session}`;
+        await this.git(['commit', '-q', '-m', message]);
+        return true;
+    }
+    // Throws away what a Step left, keeping nothing: the Step is listed as not done.
+    async revert(before) {
+        await this.git(['reset', '-q', '--hard', before]);
+        await this.git(['clean', '-q', '-fd']);
+    }
+    // Keeps what the session left on a side branch, which it names; null when it left nothing.
+    async discard(before, ticket) {
+        await this.git(['add', '-A']);
+        const moved = (await this.head()) !== before;
+        const staged = (await this.git(['diff', '--cached', '--name-only'])).trim() !== '';
+        let side = null;
+        if (moved || staged) {
+            const tree = (await this.git(['write-tree'])).trim();
+            const saved = (await this.git([
+                'commit-tree',
+                '-p',
+                'HEAD',
+                '-m',
+                `nightjar: the failed attempt at #${ticket}`,
+                tree
+            ])).trim();
+            side = `${this.at.branch}-attempt-${refPart(ticket)}`;
+            await this.git(['branch', '-f', side, saved]);
+        }
+        await this.git(['reset', '-q', '--hard', before]);
+        await this.git(['clean', '-q', '-fd']);
+        return side;
+    }
+}
+function inRoot(root, args, env) {
+    return run('git', ['-C', root, ...args], root, env);
+}
+const hasRef = async (root, ref, env) => (await inRoot(root, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], env)).ok;
+// Reuses the worktree a run before left, else the pushed branch; a worktree a stopped run left dirty is cleaned.
+export async function openWorktree(root, worktrees, branch, baseBranch, env) {
+    const must = async (args) => {
+        const got = await inRoot(root, args, env);
+        if (got.missing)
+            throw new GitFailure('git is not on the PATH.');
+        if (!got.ok)
+            throw new GitFailure(`git ${args[0] ?? ''} failed: ${firstLine(got.err)}`);
+    };
+    await must(['fetch', '-q', 'origin', baseBranch]);
+    // the branch a run before pushed, which may not be there yet
+    await inRoot(root, ['fetch', '-q', 'origin', `refs/heads/${branch}:refs/remotes/origin/${branch}`], env);
+    const base = `origin/${baseBranch}`;
+    const folder = join(worktrees, branch.slice(BRANCH_PREFIX.length));
+    const tree = new Worktree({ branch, folder, base }, env);
+    if (existsSync(folder)) {
+        await tree.git(['reset', '-q', '--hard']);
+        await tree.git(['clean', '-q', '-fd']);
+        return tree;
+    }
+    await must(['worktree', 'prune']);
+    if (await hasRef(root, `refs/heads/${branch}`, env)) {
+        await must(['worktree', 'add', '-q', folder, branch]);
+    }
+    else if (await hasRef(root, `refs/remotes/origin/${branch}`, env)) {
+        await must(['worktree', 'add', '-q', '--no-track', '-b', branch, folder, `origin/${branch}`]);
+    }
+    else {
+        await must(['worktree', 'add', '-q', '--no-track', '-b', branch, folder, base]);
+    }
+    return tree;
+}
+// The branch origin's HEAD points at, such as main, or null when origin names none.
+export async function defaultBranch(root, env) {
+    const got = await inRoot(root, ['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], env);
+    return got.ok ? got.out.trim().replace(/^origin\//, '') || null : null;
+}
+// How git signs a commit here: a locked signing key fails every commit of the run.
+export async function signing(root, env) {
+    const sign = await inRoot(root, ['config', '--bool', 'commit.gpgsign'], env);
+    if (sign.out.trim() !== 'true')
+        return 'unsigned';
+    const probe = ['commit-tree', '-S', '-p', 'HEAD', '-m', 'nightjar preflight', 'HEAD^{tree}'];
+    return (await inRoot(root, probe, env)).ok ? 'signs' : 'fails';
+}
+//# sourceMappingURL=worktree.js.map

package/dist/worktree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree.js","sourceRoot":"","sources":["../src/worktree.ts"],"names":[],"mappings":"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"}

package/docs/ticket-contract.md

@@ -0,0 +1,95 @@
+# The Ticket contract
+
+What a Ticket must hold for Nightjar to build it, on any Tracker, and the Feature file that `nightjar create` turns into a Feature and its Tickets. The words are defined in [GLOSSARY.md](../GLOSSARY.md).
+
+## A Ticket
+
+A Ticket is one child of a Feature, built as one commit. It holds:
+
+- **Acceptance criteria**, in its body: a heading named `Acceptance criteria` with a checklist under it. The Coding agent builds to them and the review reads the diff against them.
+
+  ```markdown
+  ### Acceptance criteria
+
+  - [ ] comments escape through src/escape.ts
+  - [ ] a comment with <b> shows it as text
+  ```
+
+- **Blocking links**, on the Tracker: the Tickets that must be closed, or already built on the Feature's branch, before this one is built. On GitHub these are **blocked by** links; on Azure DevOps Boards, **Predecessor** links. Tickets are built in that order, then in the Feature's own child order (the Build order). On Azure DevOps Boards the child order is the backlog rank (Stack Rank or Backlog Priority), and for children nobody has ranked, the order they were linked; so the Build order there is Predecessor links, then backlog rank, then child-link order.
+- Optionally, a **`**Model:**`** and an **`**Effort:**`** line, anywhere in its body, each on a line of its own:
+
+  ```markdown
+  **Model:** opus
+  **Effort:** high
+  ```
+
+  The first word after the colon is read, in any case; the bold is optional. A Ticket without them runs on `model` and `effort` from `factory.json`; `--model` and `--effort` on the command line win over both.
+
+A Ticket is built only while it carries the ready Signal (`ready-for-agent` by default). Its Feature carries no Signal until a person assigns it to themselves and gives it the Go (`factory-go` by default).
+
+## A Feature's Workflow
+
+A Feature may carry a **`**Workflow:**`** line anywhere in its body, on a line of its own, to add the Steps of a Workflow from `factory.json` to its build:
+
+```markdown
+**Workflow:** design-review
+```
+
+The rest of the line is the Workflow's name. Without the line the Feature gets the repo's `defaultWorkflow`, if it has one; a name no Workflow has marks the Feature as needing info. See the README's Workflows section.
+
+## The Feature file
+
+`nightjar create FILE` makes a Feature and its Tickets on the Tracker `factory.json` names, from one Markdown file:
+
+```markdown
+# Share one HTML escape
+
+The spec: the problem, the solution, the decisions. Any Markdown, headings included.
+
+## Ticket 1: Move the escape into one module
+
+**Model:** opus
+**Effort:** high
+
+What to build.
+
+### Acceptance criteria
+
+- [ ] one module exports escapeHtml
+
+## Ticket 2: Use it in the comment renderer
+
+**Blocked by:** 1
+
+What to build.
+
+### Acceptance criteria
+
+- [ ] comments escape through it
+```
+
+- The first line is `# ` and the Feature's title. Everything up to the first Ticket is the Feature's body.
+- Each Ticket starts with `## Ticket N: Title`, numbered 1, 2, 3 in the order they are to be built. A `## Ticket` line inside a fenced code block is text.
+- `**Blocked by:** 1, 2` names Tickets above it by number. It becomes blocking links on the Tracker and leaves the body; a Ticket can only wait for Tickets above it, so the links never form a loop. Leave the line out, or write `none`, for a Ticket that waits for nothing.
+- Every Ticket has acceptance criteria. `**Model:**` and `**Effort:**` lines, when there, have a value, and stay in the body as written.
+
+`nightjar create --dry-run FILE` reads the file and says what it would make, making nothing. A file out of this shape is refused before anything is made, with every fault and its line.
+
+`nightjar create` then makes, in order: the Feature, with no Signal; each Ticket as its last child, linked to its blockers and then given the ready Signal. It prints each with the Tracker's reference (`#12`, `AB#12`). If the Tracker fails part way, it names what it made before the fault and undoes nothing. It never assigns the Feature and never gives the Go: that stays with a person.
+
+| Tracker               | The Feature                    | Each Ticket                                       | Blocking links      |
+| --------------------- | ------------------------------ | ------------------------------------------------- | ------------------- |
+| GitHub Issues         | an issue                       | an issue, made a sub-issue of the Feature          | blocked by          |
+| Azure DevOps Boards   | a work item of `featureType`   | a child work item of `ticketType`                 | Predecessor         |
+| A module              | `createFeature`                | `createTicket`                                    | `block`             |
+
+On Azure DevOps Boards, `factory.json` names the work item type of a Ticket as `tracker.ticketType` (such as `User Story`, `Product Backlog Item` or `Issue`); without it `nightjar create` refuses. Bodies are written as Markdown. A Tracker module makes Features when it has all three methods of `FeatureWriter` ([custom-adapters.md](custom-adapters.md)).
+
+## The skill
+
+The package ships a Claude Code skill, `nightjar-feature`, that writes a Feature file from an agreed idea and makes it with `nightjar create`. It needs no other skill. To use it in a repo:
+
+```bash
+mkdir -p .claude/skills
+cp -R "$(npm root -g)/@nonameolsson/nightjar/skills/nightjar-feature" .claude/skills/
+```

package/package.json

@@ -1,6 +1,75 @@
 {
-  "name": "@nonameolsson/nightjar",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@nonameolsson/nightjar",
+	"version": "0.2.0",
+	"description": "Builds a repo's Features from its Tracker with nobody at the keyboard, one draft pull request per Feature.",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/nonameolsson/nightjar.git"
+	},
+	"homepage": "https://github.com/nonameolsson/nightjar#readme",
+	"bugs": {
+		"url": "https://github.com/nonameolsson/nightjar/issues"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"keywords": [
+		"claude-code",
+		"agent",
+		"automation",
+		"github",
+		"azure-devops"
+	],
+	"type": "module",
+	"bin": {
+		"nightjar": "dist/cli.js"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		},
+		"./schema/factory.schema.json": "./schema/factory.schema.json"
+	},
+	"files": [
+		"dist",
+		"!dist/**/*.spec.*",
+		"schema",
+		"skills",
+		"docs/ticket-contract.md",
+		"plugin/nightjar-status",
+		"!plugin/**/*.spec.ts",
+		"src/status-shape.ts"
+	],
+	"engines": {
+		"node": ">=24"
+	},
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json",
+		"typecheck": "tsc --noEmit && tsc --noEmit -p plugin",
+		"lint": "eslint .",
+		"format": "prettier --write .",
+		"format:check": "prettier --check .",
+		"test": "vitest run",
+		"schema": "tsx scripts/schema.ts",
+		"leaks": "tsx scripts/leak-check.ts",
+		"pack:check": "tsx scripts/pack-install.ts",
+		"check": "npm run typecheck && npm run lint && npm run format:check && npm test && npm run build && npm run leaks && npm run pack:check",
+		"prepack": "npm run build"
+	},
+	"dependencies": {
+		"zod": "^4.6.7"
+	},
+	"devDependencies": {
+		"@eslint/js": "^10.0.1",
+		"@types/node": "^24",
+		"eslint": "^10.14.0",
+		"eslint-config-prettier": "^10.1.8",
+		"prettier": "^3.9.10",
+		"tsx": "^4.23.15",
+		"typescript": "^6.0.3",
+		"typescript-eslint": "^8.72.1",
+		"vitest": "^5.0.5"
+	}
+}

package/plugin/nightjar-status/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+	"name": "nightjar-status",
+	"version": "0.1.0",
+	"description": "Nightjar in the Claude Code status line, and a toast when it builds a Ticket, opens a pull request or needs a person."
+}

package/plugin/nightjar-status/hooks/format.ts

@@ -0,0 +1,48 @@
+// What the status line and the toasts say, from .factory/status.json (shape: src/status-shape.ts).
+import type { Event, Status } from '../../../src/status-shape.js';
+
+const two = (n: number) => String(n).padStart(2, '0');
+const clock = (iso: string) => {
+	const d = new Date(iso);
+	return `${two(d.getHours())}:${two(d.getMinutes())}`;
+};
+const minutes = (from: string, nowMs: number) =>
+	`${String(Math.max(0, Math.round((nowMs - Date.parse(from)) / 60_000)))}m`;
+const sameDay = (iso: string, nowMs: number) =>
+	new Date(iso).toDateString() === new Date(nowMs).toDateString();
+
+// The status line, or undefined when Nightjar is off.
+export function line(status: Status, nowMs: number): string | undefined {
+	const said = what(status, nowMs);
+	if (said === undefined || !status.codeMoved) return said;
+	return `${said} · restart: main has new Nightjar code (${status.codeMoved})`;
+}
+
+function what(status: Status, nowMs: number): string | undefined {
+	const d = status.doing;
+	// the file keeps yesterday's spend until Nightjar writes again
+	const spent = sameDay(status.at, nowMs) ? status.spentTodayUsd : 0;
+	const today = `$${spent.toFixed(2)} today`;
+	if (d.kind === 'off') return undefined;
+	if (d.kind === 'idle') return `nightjar: idle, next poll ${clock(d.nextPollAt)} · ${today}`;
+	if (d.kind === 'paused') {
+		const until = d.until ? ` until ${clock(d.until)}` : '';
+		return `nightjar: paused${until}: ${d.why} · ${today}`;
+	}
+	const where = d.ticket === null ? `#${d.feature}` : `#${d.feature} › #${d.ticket}`;
+	const round =
+		d.round !== null && d.rounds !== null && (d.step === 'fix' || d.round > 1)
+			? ` ${String(d.round)}/${String(d.rounds)}`
+			: '';
+	return `nightjar: ${where} ${d.step}${round} · ${minutes(d.startedAt, nowMs)} · ${today}`;
+}
+
+export function toast(e: Event): string {
+	if (e.kind === 'built') return `nightjar: #${e.ticket} built (#${e.feature})`;
+	if (e.kind === 'pull') return `nightjar: #${e.feature} draft pull request ${e.url}`;
+	if (e.kind === 'failed') return `nightjar: #${e.feature} failed: ${e.why}`;
+	if (e.kind === 'stale') {
+		return `nightjar: main has new Nightjar code (${e.commit}); restart it from an updated main`;
+	}
+	return `nightjar: #${e.ticket ?? e.feature} needs a person: ${e.why}`;
+}

package/plugin/nightjar-status/hooks/hooks.json

@@ -0,0 +1 @@
+{ "modules": ["./register.ts"] }

package/plugin/nightjar-status/hooks/register.ts

@@ -0,0 +1,51 @@
+import type { EngineInterface, Register } from 'claude-code';
+import type { Status } from '../../../src/status-shape.js';
+import { line, toast } from './format';
+
+const EVERY_MS = 5_000;
+
+// undefined until the first read, which takes the events already there without toasting them
+let seen: number | undefined;
+
+// .factory/ is in the main checkout, the folder that holds the git common dir, worktree or not
+async function statusFile($: EngineInterface): Promise<string | undefined> {
+	const git = await $.process.run([
+		'git',
+		'rev-parse',
+		'--path-format=absolute',
+		'--git-common-dir'
+	]);
+	if (git.exitCode !== 0) return undefined;
+	return `${git.stdout.trim().replace(/\/\.git$/, '')}/.factory/status.json`;
+}
+
+async function tick($: EngineInterface, path: string): Promise<void> {
+	if (!(await $.fs.exists(path))) return $.ui.status(undefined);
+	let status: Status;
+	try {
+		status = JSON.parse(await $.fs.read(path)) as Status;
+	} catch {
+		// Nightjar renames its writes into place, so this is a file someone broke; wait for the next
+		return;
+	}
+	if (seen !== undefined) {
+		for (const e of status.recent) if (e.seq > seen) $.ui.toast(toast(e), { timeoutMs: 8_000 });
+	}
+	seen = status.recent.at(-1)?.seq ?? 0;
+	const isOff = status.doing.kind === 'off';
+	if (!isOff && (await $.process.run(['kill', '-0', String(status.pid)])).exitCode !== 0) {
+		return $.ui.status('nightjar: stopped without writing off');
+	}
+	$.ui.status(line(status, await $.clock.now()));
+}
+
+export const register: Register = (on) => {
+	on('session.start', async ($, e, next) => {
+		const done = await next(e);
+		const path = await statusFile($);
+		if (path === undefined) return done;
+		await tick($, path);
+		$.clock.every(EVERY_MS, () => void tick($, path));
+		return done;
+	});
+};