@dpeek/codeless 0.1.0 → 0.1.1

package/README.md

@@ -154,9 +154,18 @@ planners or worktree shells are running.
   worktree/<slug>/    # stream/<slug> branch
   worktree/main/      # example integration checkout location
   .land-lock/         # shared landing owner and recorded integration commit
-  metrics/<slug>/NNN.json # first dispatch, landing time, and landed commit
+  metrics/<slug>/NNN.json # dispatch/landing times and deduplicated implementer attempts
 ```
 
+Run `codeless init` once after configuring a project. It creates the shared state
+layout and the dedicated integration worktree at
+`<workspace>/worktree/<integration-branch>` without requiring Herdr. For the
+default workspace it adds only `/.codeless/state/` to the primary checkout's
+`.gitignore`; an absolute workspace override does not modify repository ignores.
+It is safe to repeat when that exact worktree is registered. It stops rather
+than moving a branch checkout, replacing an occupied target, or broadening a
+repository ignore rule that covers configuration or prompts.
+
 Normal `git clean -fd` preserves ignored state. `git clean -fdx` removes ignored
 files and can therefore destroy local Codeless journals, metrics, and worktrees;
 inspect its targets before using it.
@@ -167,6 +176,7 @@ Run creation, opening, and planner launch from a Herdr-managed shell. Landing
 needs no Herdr session.
 
 ```sh
+codeless init
 codeless create <slug>
 codeless open <slug>
 codeless planner <slug>
@@ -177,21 +187,35 @@ codeless next <numbered-change-file> <landed-commit>
 codeless metrics
 ```
 
-Slugs are lowercase kebab-case, at most 24 characters. `create` starts
+Slugs are lowercase kebab-case, at most 24 characters. `init` validates the
+existing configuration and integration branch, reports the branch, primary
+checkout, workspace, and integration worktree, then creates only the shared
+state directories and canonical integration worktree when absent. All other
+commands validate their prerequisites and never bootstrap this setup. `create` starts
 `stream/<slug>` from the integration branch and creates its local documents;
 it refuses existing streams. `open` resumes a stream. Both run the configured
 install command, then validate and open a planner beside an idle shell. `planner`
 starts Pi in an existing stream's lone shell after the same role preflight. Its
 activation establishes the same identity as creation and reopening.
 Dispatch validates the implementer selection before touching the planner's
-right-hand pane, starts a fresh ephemeral implementer, and waits for completion.
+right-hand pane, starts a fresh ephemeral implementer with Codeless's reporting
+extension and its explicit Pi extension flag, and waits for completion. Its JSON
+result is a normalized attempt report, which the planner tool exposes before
+queueing review. It includes the actual settled model/thinking selection,
+terminal text and outcome, full-session Pi usage and available Pi cost estimate,
+timestamps, and tool/error counts; prompts, source, thinking, credentials, and
+transcripts are not retained.
 
 The first valid dispatch creates one atomic local JSON metric record for its
-stream and numbered change. Retries preserve its original dispatch time. After a
-successful integration fast-forward, Codeless records the landed time and commit
-on that change's canonical record, creating a landed record without elapsed time
-when dispatch collection was unavailable; collection warnings never alter
-dispatch or landing.
+stream and numbered change. Each accepted run receives a new attempt ID and is
+added idempotently under that record; re-ingesting an ID preserves the original
+attempt and retries preserve the original dispatch time. Missing, malformed, or
+unwritable collection data warns and stores an incomplete attempt when possible
+without retrying or failing a settled implementation. After a successful
+integration fast-forward, Codeless records the landed time and commit on that
+change's canonical record, creating a landed record without elapsed time when
+dispatch collection was unavailable; collection warnings never alter dispatch or
+landing.
 `codeless metrics` prints every recorded stream and a project total. Its elapsed
 columns are dispatch-to-land wall-clock time; among landed changes, records
 without a measured duration are explicitly unavailable. Dispatched-but-unlanded
@@ -233,8 +257,35 @@ From this package directory, run `bun run check` for formatting, lint, types,
 and tests, or `bun run test` for tests alone. The integration tests use real Git
 worktrees and mock Herdr/Pi commands; they never launch actual agents.
 
-`npm publish` runs the full check through `prepublishOnly` and publishes
-`@dpeek/codeless` with public access.
+From a clean `main` checkout, publish the next patch release with:
+
+```sh
+bun run release
+```
+
+The script verifies npm authentication, runs the full check and an npm package
+dry run, increments the patch version, commits `package.json` with the version as
+the complete commit message, creates the matching version tag, and publishes
+`@dpeek/codeless`. It intentionally does not push the commit or tag.
+
+For non-interactive local publishing, create an npm granular access token with
+read/write access to `@dpeek/codeless` (or the `@dpeek` scope) and **Bypass 2FA**
+enabled. Put the token in the repository's ignored `.env` file:
+
+```sh
+NPM_TOKEN=npm_your_token_here
+```
+
+Reference that variable from your user-level `~/.npmrc`:
+
+```ini
+//registry.npmjs.org/:_authToken=${NPM_TOKEN}
+```
+
+`bun run release` loads `.env` and passes the token to npm. Never put the token
+directly in a committed `.npmrc` or source file. If npm package settings disallow
+tokens, publishing will still require an OTP. For hosted CI, prefer npm trusted
+publishing instead of a long-lived token.
 
 Keep source, tests, executable, extension, and dependencies inside this project.
 Keep project policies and real prompts outside it. Add automation only for

package/extension/implementer-reporting.js

@@ -0,0 +1,147 @@
+import { existsSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+
+function text(message) {
+  if (message?.role !== "assistant" || !Array.isArray(message.content)) return undefined;
+  const value = message.content
+    .filter((part) => part?.type === "text" && typeof part.text === "string")
+    .map((part) => part.text)
+    .join("");
+  return value || undefined;
+}
+
+function validUsage(value) {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    ["input", "output", "cacheRead", "cacheWrite"].every(
+      (key) => Number.isFinite(value[key]) && value[key] >= 0,
+    )
+  );
+}
+
+function sessionUsage(entries) {
+  const usages = [];
+  for (const entry of entries) {
+    if (
+      entry?.type === "message" &&
+      (entry.message?.role === "assistant" || entry.message?.role === "toolResult") &&
+      validUsage(entry.message.usage)
+    )
+      usages.push(entry.message.usage);
+    if (
+      (entry?.type === "compaction" || entry?.type === "branch_summary") &&
+      validUsage(entry.usage)
+    )
+      usages.push(entry.usage);
+  }
+  if (usages.length === 0) return undefined;
+  const total = (key) => usages.reduce((sum, usage) => sum + usage[key], 0);
+  const costs = usages.map((usage) => usage.cost?.total);
+  return {
+    input: total("input"),
+    output: total("output"),
+    cacheRead: total("cacheRead"),
+    cacheWrite: total("cacheWrite"),
+    ...(costs.every((cost) => Number.isFinite(cost) && cost >= 0)
+      ? {
+          cost: {
+            amount: costs.reduce((sum, cost) => sum + cost, 0),
+            currency: "USD",
+            source: "pi-model-estimate",
+          },
+        }
+      : {}),
+  };
+}
+
+function messages(entries) {
+  return entries
+    .filter((entry) => entry?.type === "message")
+    .map((entry) => entry.message)
+    .filter((message) => message?.role === "assistant" || message?.role === "toolResult");
+}
+
+function write(path, value) {
+  const temporary = `${path}.${process.pid}.${crypto.randomUUID()}`;
+  try {
+    writeFileSync(temporary, `${JSON.stringify(value)}\n`, { flag: "wx" });
+    renameSync(temporary, path);
+  } finally {
+    if (existsSync(temporary)) unlinkSync(temporary);
+  }
+}
+
+export default function implementerReportingExtension(pi) {
+  pi.registerFlag("codeless-attempt", { type: "string" });
+  let configuration;
+  let startedAt;
+  let toolCalls = 0;
+  let errorCount = 0;
+  pi.on("session_start", () => {
+    try {
+      const value = JSON.parse(pi.getFlag("codeless-attempt") ?? "");
+      if (
+        typeof value?.path === "string" &&
+        typeof value?.id === "string" &&
+        typeof value?.stream === "string" &&
+        typeof value?.change === "string"
+      )
+        configuration = value;
+    } catch {}
+  });
+  pi.on("agent_start", () => {
+    startedAt ??= new Date().toISOString();
+  });
+  pi.on("tool_execution_end", (event) => {
+    toolCalls += 1;
+    if (event.isError) errorCount += 1;
+  });
+  pi.on("agent_settled", (_event, ctx) => {
+    if (configuration === undefined) return;
+    const report = configuration;
+    configuration = undefined;
+    const settledMessages = messages(ctx.sessionManager.getEntries());
+    const final = [...settledMessages].reverse().find((message) => message.role === "assistant");
+    const totals = sessionUsage(ctx.sessionManager.getEntries());
+    const model = final?.responseModel ?? final?.model ?? ctx.model?.id;
+    const provider = final?.provider ?? ctx.model?.provider;
+    const selection =
+      typeof provider === "string" &&
+      typeof model === "string" &&
+      typeof pi.getThinkingLevel() === "string"
+        ? { provider, model, thinking: pi.getThinkingLevel() }
+        : undefined;
+    const finalText = text(final);
+    const complete =
+      selection !== undefined &&
+      typeof final?.stopReason === "string" &&
+      final.stopReason.length > 0 &&
+      finalText !== undefined &&
+      totals !== undefined;
+    write(report.path, {
+      id: report.id,
+      stream: report.stream,
+      change: report.change,
+      role: "implementer",
+      startedAt: startedAt ?? new Date().toISOString(),
+      endedAt: new Date().toISOString(),
+      ...(selection === undefined ? {} : { selection }),
+      outcome: final?.stopReason ?? "unknown",
+      ...(finalText === undefined ? {} : { text: finalText }),
+      ...(totals === undefined
+        ? {}
+        : {
+            usage: {
+              input: totals.input,
+              output: totals.output,
+              cacheRead: totals.cacheRead,
+              cacheWrite: totals.cacheWrite,
+            },
+            ...(totals.cost === undefined ? {} : { cost: totals.cost }),
+          }),
+      toolCalls,
+      errorCount,
+      incomplete: !complete,
+    });
+  });
+}

package/extension/planner.js

@@ -1,4 +1,5 @@
 import { fileURLToPath } from "node:url";
+import { validAttempt } from "../src/attempt.ts";
 
 const codeless = fileURLToPath(new URL("../bin/codeless", import.meta.url));
 const thinkingLevels = new Set(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
@@ -322,13 +323,22 @@ export default function plannerExtension(pi) {
         if (execution.code !== 0) {
           throw new Error(output || `codeless dispatch failed with exit code ${execution.code}`);
         }
+        let attempt;
+        try {
+          attempt = JSON.parse(execution.stdout);
+        } catch {
+          throw new Error("Codeless returned an invalid implementer attempt");
+        }
+        if (!validAttempt(attempt, attempt?.stream, attempt?.change)) {
+          throw new Error("Codeless returned an invalid implementer attempt");
+        }
         pi.sendUserMessage(`/review ${JSON.stringify(changePath)}`, {
           deliverAs: "steer",
           expandPromptTemplates: true,
         });
         return {
-          content: [{ type: "text", text: output || "Implementer settled." }],
-          details: { changePath },
+          content: [{ type: "text", text: attempt.text || "Implementer settled." }],
+          details: { changePath, attempt },
         };
       },
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dpeek/codeless",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "An attended planner and implementer workflow for parallel capability development",
   "homepage": "https://github.com/dpeek/codeless#readme",
   "bugs": {
@@ -27,7 +27,7 @@
   },
   "scripts": {
     "check": "oxfmt --config .oxfmtrc.json --write . && oxlint --config .oxlintrc.json --fix --type-aware --type-check . && bun run test",
-    "prepublishOnly": "bun run check",
+    "release": "bun ./scripts/release.ts",
     "test": "bun test ./test --dots"
   },
   "dependencies": {

package/spec/workflow.md

@@ -49,6 +49,18 @@ Git-ignored, and every linked worktree resolves the same primary-checkout state:
   metrics/<slug>/NNN.json
 ```
 
+`codeless init` is the explicit, idempotent bootstrap for a configured project.
+It requires the configured integration branch to exist and creates the shared
+state directories plus that branch's worktree only at
+`<workspace>/worktree/<integration-branch>`. It reuses only the exact registered
+canonical checkout. An occupied target, a branch registered elsewhere, invalid
+checkout, or ambiguous Git registration stops unchanged; init never switches
+branches, moves worktrees, or repairs conflicts. With the default workspace,
+it accepts a repository ignore rule only when it ignores the state path without
+covering configuration or configured prompts, otherwise appending the narrow
+`/.codeless/state/` rule. An absolute workspace never changes repository
+ignores. No other command bootstraps this layout.
+
 `planner.md` owns decisions, approvals, review outcomes, landing history, and
 the context needed by a fresh planner. `change.md` is the editable current
 proposal. `changes/NNN.md` is the immutable-by-policy approved input to one
@@ -108,7 +120,23 @@ right-hand Herdr pane only when that pane is an available shell or the expected
 idle implementer, starts a fresh ephemeral Pi implementer in the stream
 worktree, submits `/implement`, and waits for at most one hour.
 
-Successful dispatch queues the expanded `/review` prompt back into the planner.
+Successful dispatch loads the package-owned reporting extension while retaining
+`--no-session` and passes its report configuration through that extension's
+explicit Pi string flag, then returns one normalized attempt to the planner tool
+before it queues the expanded `/review` prompt. Attempts have a stable ID and
+capture only stream/change/role, start and settlement timestamps, Pi's actual
+settled provider/model/thinking selection, terminal outcome and final text,
+full-session Pi input/output/cache usage (including tool results, compaction,
+and branch summaries), available Pi model cost estimate with USD currency and
+source, and tool/error counts. Cost is omitted when Pi did not supply valid
+cost totals. They do not retain prompts, source, credentials, thinking, or a
+transcript. The extension writes its narrow report atomically once, then
+remains disarmed for remediation; Codeless atomically deduplicates it inside the
+per-change metric record, rejecting a
+conflicting duplicate ID. Missing, malformed, or unwritable collection warns
+and yields an explicitly incomplete attempt when possible without failing or
+repeating a settled implementation.
+
 The planner inspects the full diff and relevant code, checks the approved
 acceptance criteria, and runs focused checks when the implementation output is
 insufficient. Remediation reuses the same implementer context. Once approved,
@@ -116,10 +144,8 @@ the planner records the review result, exits the implementer so its pane returns
 to a shell, and follows the commit-and-land prompt without another approval
 round.
 
-Dispatch and remediation do not retry automatically. Dispatch currently exposes
-Herdr command output rather than a normalized implementation result, and
-remediation and implementer shutdown are still performed through prompt-owned
-Herdr commands.
+Dispatch and remediation do not retry automatically. Remediation and implementer
+shutdown are still performed through prompt-owned Herdr commands.
 
 ## Commit and landing
 
@@ -162,10 +188,11 @@ before another implementation.
 ## Local workflow metrics
 
 The first dispatch for a stream and numbered change creates one atomic local
-metric record. Retrying dispatch preserves the original timestamp. Successful
-landing adds its timestamp and commit, or creates a landed record with
-unavailable elapsed time when dispatch collection was unavailable. Collection
-warnings do not change dispatch or landing outcomes.
+metric record. Every accepted dispatch creates a new attempt ID; re-ingesting an
+attempt ID is atomic and idempotent, while the original dispatch timestamp stays
+unchanged. Successful landing adds its timestamp and commit, or creates a landed
+record with unavailable elapsed time when dispatch collection was unavailable.
+Collection warnings do not change dispatch or landing outcomes.
 
 `codeless metrics` reports every recorded stream and a project total with:
 
@@ -174,9 +201,9 @@ warnings do not change dispatch or landing outcomes.
 - total and average dispatch-to-land wall-clock time.
 
 The measurements are prospective, local observations. They are not journal
-state, an approval source, or a recovery mechanism. Token usage, cost,
-normalized attempt results, review rework, and failure breakdowns are not yet
-collected.
+state, an approval source, or a recovery mechanism. Attempt usage and cost are
+stored for later aggregation; `codeless metrics`, review rework, and failure
+breakdowns do not yet report them.
 
 ## Limits
 

package/src/attempt.ts

@@ -0,0 +1,101 @@
+export type Attempt = {
+  id: string;
+  stream: string;
+  change: string;
+  role: "implementer";
+  startedAt: string;
+  endedAt: string;
+  selection?: { provider: string; model: string; thinking: string };
+  outcome: string;
+  text?: string;
+  usage?: { input: number; output: number; cacheRead: number; cacheWrite: number };
+  cost?: { amount: number; currency: string; source: string };
+  toolCalls: number;
+  errorCount: number;
+  incomplete: boolean;
+};
+
+export function validAttempt(value: unknown, stream: string, change: string): value is Attempt {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const attempt = value as Record<string, unknown>;
+  const allowed = new Set([
+    "id",
+    "stream",
+    "change",
+    "role",
+    "startedAt",
+    "endedAt",
+    "selection",
+    "outcome",
+    "text",
+    "usage",
+    "cost",
+    "toolCalls",
+    "errorCount",
+    "incomplete",
+  ]);
+  const strings = ["id", "stream", "change", "role", "startedAt", "endedAt", "outcome"];
+  if (
+    !Object.keys(attempt).every((key) => allowed.has(key)) ||
+    !strings.every((key) => typeof attempt[key] === "string" && attempt[key].length > 0) ||
+    !Number.isFinite(Date.parse(attempt["startedAt"] as string)) ||
+    !Number.isFinite(Date.parse(attempt["endedAt"] as string)) ||
+    attempt["stream"] !== stream ||
+    attempt["change"] !== change ||
+    attempt["role"] !== "implementer" ||
+    !Number.isSafeInteger(attempt["toolCalls"]) ||
+    (attempt["toolCalls"] as number) < 0 ||
+    !Number.isSafeInteger(attempt["errorCount"]) ||
+    (attempt["errorCount"] as number) < 0 ||
+    typeof attempt["incomplete"] !== "boolean"
+  )
+    return false;
+  const selection = attempt["selection"];
+  if (
+    selection !== undefined &&
+    (typeof selection !== "object" ||
+      selection === null ||
+      ["provider", "model", "thinking"].some(
+        (key) =>
+          typeof (selection as Record<string, unknown>)[key] !== "string" ||
+          !(selection as Record<string, unknown>)[key],
+      ))
+  )
+    return false;
+  const usage = attempt["usage"];
+  if (
+    usage !== undefined &&
+    (typeof usage !== "object" ||
+      usage === null ||
+      ["input", "output", "cacheRead", "cacheWrite"].some(
+        (key) =>
+          !Number.isSafeInteger((usage as Record<string, unknown>)[key]) ||
+          ((usage as Record<string, unknown>)[key] as number) < 0,
+      ))
+  )
+    return false;
+  if (
+    attempt["incomplete"] === false &&
+    (selection === undefined ||
+      usage === undefined ||
+      attempt["outcome"] === "unknown" ||
+      typeof attempt["text"] !== "string" ||
+      attempt["text"].length === 0)
+  )
+    return false;
+  const cost = attempt["cost"];
+  if (
+    cost !== undefined &&
+    (usage === undefined ||
+      typeof cost !== "object" ||
+      cost === null ||
+      !Number.isFinite((cost as Record<string, unknown>)["amount"]) ||
+      ((cost as Record<string, unknown>)["amount"] as number) < 0 ||
+      typeof (cost as Record<string, unknown>)["currency"] !== "string" ||
+      !(cost as Record<string, unknown>)["currency"] ||
+      typeof (cost as Record<string, unknown>)["source"] !== "string" ||
+      !(cost as Record<string, unknown>)["source"])
+  )
+    return false;
+  return attempt["text"] === undefined || typeof attempt["text"] === "string";
+}

package/src/cli.ts

@@ -8,6 +8,7 @@ import {
   readdirSync,
   realpathSync,
   rmdirSync,
+  statSync,
   unlinkSync,
   writeFileSync,
 } from "node:fs";
@@ -15,11 +16,13 @@ import { mkdir, writeFile } from "node:fs/promises";
 import { createHash } from "node:crypto";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 
-import { metricReport, recordDispatch, recordLanding } from "./metrics.ts";
+import { metricReport, recordAttempt, recordDispatch, recordLanding } from "./metrics.ts";
+import { type Attempt, validAttempt } from "./attempt.ts";
 import { roleSelectionArguments, roleSelectionSummary, validateRoleSelection } from "./pi.ts";
 import { readProject } from "./project.ts";
 
 const usage = `Usage:
+  codeless init
   codeless create <slug>
   codeless open <slug>
   codeless planner <slug>
@@ -36,9 +39,14 @@ export async function runCodeless(args: string[]): Promise<void> {
     return;
   }
   const repository = canonicalPath(run("git", ["rev-parse", "--show-toplevel"]).trim());
-  const { integrationBranch } = readProject(repository);
+  const project = readProject(repository);
+  const { integrationBranch } = project;
   run("git", ["check-ref-format", "--branch", integrationBranch], repository);
   const plannerExtension = resolve(import.meta.dir, "../extension/planner.js");
+  const implementerReportingExtension = resolve(
+    import.meta.dir,
+    "../extension/implementer-reporting.js",
+  );
   const configuredWorkspace = Bun.spawnSync(
     ["git", "config", "--local", "--get", "codeless.workspaceRoot"],
     { cwd: repository },
@@ -123,28 +131,146 @@ export async function runCodeless(args: string[]): Promise<void> {
       .join("-");
   }
 
-  function integrationWorktree(): string {
-    const entries = run("git", ["worktree", "list", "--porcelain", "-z"], repository).split("\0\0");
-    for (const entry of entries) {
-      const fields = entry.split("\0");
-      if (fields.includes(`branch refs/heads/${integrationBranch}`)) {
+  type Worktree = { path: string; branch?: string };
+
+  function registeredWorktrees(): Worktree[] {
+    return run("git", ["worktree", "list", "--porcelain", "-z"], repository)
+      .split("\0\0")
+      .filter(Boolean)
+      .map((entry) => {
+        const fields = entry.split("\0");
         const path = fields.find((field) => field.startsWith("worktree "))?.slice(9);
-        if (path !== undefined) return path;
-      }
-    }
-    throw new Error(`${integrationBranch} needs a dedicated integration worktree`);
+        if (path === undefined) throw new Error("Git did not report a worktree path");
+        const branch = fields.find((field) => field.startsWith("branch "))?.slice(7);
+        return { path: canonicalPath(path), ...(branch === undefined ? {} : { branch }) };
+      });
+  }
+
+  function integrationWorktree(): string {
+    const matches = registeredWorktrees().filter(
+      (worktree) => worktree.branch === `refs/heads/${integrationBranch}`,
+    );
+    if (matches.length !== 1)
+      throw new Error(`${integrationBranch} needs exactly one dedicated integration worktree`);
+    return matches[0]!.path;
   }
 
   function primaryWorktree(): string {
-    const entry = run("git", ["worktree", "list", "--porcelain", "-z"], repository).split(
-      "\0\0",
-    )[0];
-    const path = entry
-      ?.split("\0")
-      .find((field) => field.startsWith("worktree "))
-      ?.slice(9);
+    const path = registeredWorktrees()[0]?.path;
     if (path === undefined) throw new Error("Git did not report a primary worktree");
-    return canonicalPath(path);
+    return path;
+  }
+
+  function init(): void {
+    run("git", ["show-ref", "--verify", `refs/heads/${integrationBranch}`], repository);
+    const primary = primaryWorktree();
+    const target = canonicalPath(join(workspaceRoot, "worktree", integrationBranch));
+    const matchingBranch = registeredWorktrees().filter(
+      (worktree) => worktree.branch === `refs/heads/${integrationBranch}`,
+    );
+    const targetExists = existsSync(target);
+
+    let workspaceParent = workspaceRoot;
+    while (!existsSync(workspaceParent)) workspaceParent = dirname(workspaceParent);
+    if (!statSync(workspaceParent).isDirectory()) {
+      throw new Error(`Workspace parent is not a directory: ${workspaceParent}`);
+    }
+    const worktreeRoot = join(workspaceRoot, "worktree");
+    const stateDirectories: [string, string][] = [
+      ["Workspace", workspaceRoot],
+      ["Workspace stream path", join(workspaceRoot, "stream")],
+      ["Workspace worktree path", worktreeRoot],
+      ["Workspace metrics path", join(workspaceRoot, "metrics")],
+    ];
+    for (const [label, path] of stateDirectories) {
+      if (existsSync(path) && !statSync(path).isDirectory()) {
+        throw new Error(`${label} is not a directory: ${path}`);
+      }
+    }
+    const defaultWorkspace = workspaceRoot === canonicalPath(join(primary, ".codeless", "state"));
+    const ignoreFile = join(primary, ".gitignore");
+    let stateIgnored = false;
+    if (defaultWorkspace) {
+      if (existsSync(ignoreFile) && !statSync(ignoreFile).isFile()) {
+        throw new Error(`Repository ignore file is not a file: ${ignoreFile}`);
+      }
+
+      function ignoredByRepository(path: string): boolean {
+        const effective = Bun.spawnSync(["git", "check-ignore", "-q", "--no-index", path], {
+          cwd: primary,
+          env: process.env,
+          stdin: "ignore",
+          stdout: "ignore",
+          stderr: "pipe",
+        });
+        if (effective.exitCode === 1) return false;
+        if (effective.exitCode !== 0) {
+          throw new Error(
+            effective.stderr.toString().trim() || "Could not inspect repository ignores",
+          );
+        }
+        const source = run("git", ["check-ignore", "-v", "--no-index", path], primary).split(
+          ":",
+          1,
+        )[0];
+        return source === ".gitignore" || source === ignoreFile;
+      }
+
+      const protectedPaths = [
+        ".codeless/config.json",
+        ...["change", "implement", "review", "commit"].map((name) =>
+          join(project.prompts, `${name}.md`),
+        ),
+      ];
+      if (protectedPaths.some((path) => ignoredByRepository(path))) {
+        throw new Error(
+          `Repository ignore rule conflicts with Codeless configuration or prompts; narrow ${ignoreFile} to /.codeless/state/`,
+        );
+      }
+      stateIgnored = ignoredByRepository(join(".codeless", "state", ".codeless-init-probe"));
+    }
+
+    if (matchingBranch.length > 1) {
+      throw new Error(`Git reports ${integrationBranch} checked out in multiple worktrees`);
+    }
+    if (matchingBranch.length === 1 && matchingBranch[0]!.path !== target) {
+      throw new Error(
+        `${integrationBranch} is checked out at ${matchingBranch[0]!.path}, expected ${target}`,
+      );
+    }
+    if (matchingBranch.length === 1 && (!targetExists || !statSync(target).isDirectory())) {
+      throw new Error(
+        `Git registers ${integrationBranch} at invalid integration worktree ${target}`,
+      );
+    }
+    if (
+      matchingBranch.length === 1 &&
+      run("git", ["branch", "--show-current"], target).trim() !== integrationBranch
+    ) {
+      throw new Error(`Integration worktree is not on ${integrationBranch}: ${target}`);
+    }
+    if (matchingBranch.length === 0 && targetExists) {
+      throw new Error(`Integration worktree target is occupied: ${target}`);
+    }
+
+    if (defaultWorkspace && !stateIgnored) {
+      const currentIgnore = existsSync(ignoreFile) ? readFileSync(ignoreFile, "utf8") : "";
+      appendFileSync(
+        ignoreFile,
+        `${currentIgnore.length > 0 && !currentIgnore.endsWith("\n") ? "\n" : ""}/.codeless/state/\n`,
+      );
+    }
+    mkdirSync(join(workspaceRoot, "stream"), { recursive: true });
+    mkdirSync(worktreeRoot, { recursive: true });
+    mkdirSync(join(workspaceRoot, "metrics"), { recursive: true });
+    if (matchingBranch.length === 0) {
+      run("git", ["worktree", "add", target, integrationBranch], repository);
+    }
+
+    console.log(`Integration branch: ${integrationBranch}`);
+    console.log(`Primary checkout: ${primary}`);
+    console.log(`Workspace: ${workspaceRoot}`);
+    console.log(`Integration worktree: ${target}`);
   }
 
   function requireDirection(slug: string, worktree: string): string {
@@ -313,6 +439,48 @@ export async function runCodeless(args: string[]): Promise<void> {
     }
   }
 
+  function incompleteAttempt(
+    id: string,
+    slug: string,
+    number: string,
+    selection: { provider: string; model: string; thinking: string },
+  ): Attempt {
+    const timestamp = new Date().toISOString();
+    return {
+      id,
+      stream: slug,
+      change: number,
+      role: "implementer",
+      startedAt: timestamp,
+      endedAt: timestamp,
+      selection,
+      outcome: "unknown",
+      toolCalls: 0,
+      errorCount: 0,
+      incomplete: true,
+    };
+  }
+
+  function collectedAttempt(value: unknown, fallback: Attempt): Attempt {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) return fallback;
+    const attempt = value as Partial<Attempt>;
+    if (
+      attempt.id !== fallback.id ||
+      attempt.stream !== fallback.stream ||
+      attempt.change !== fallback.change ||
+      attempt.role !== "implementer" ||
+      typeof attempt.startedAt !== "string" ||
+      typeof attempt.endedAt !== "string" ||
+      typeof attempt.outcome !== "string" ||
+      typeof attempt.toolCalls !== "number" ||
+      typeof attempt.errorCount !== "number" ||
+      attempt.incomplete !== false ||
+      !validAttempt(attempt, fallback.stream, fallback.change)
+    )
+      return fallback;
+    return attempt;
+  }
+
   function latestChangeNumber(slug: string): string {
     const change = readdirSync(join(workspaceRoot, "stream", slug, "changes"))
       .filter((file) => /^\d{3}\.md$/.test(file))
@@ -538,9 +706,11 @@ export async function runCodeless(args: string[]): Promise<void> {
     requireClean(worktree, branch);
     const prompts = promptDirectory(worktree);
     const selection = readProject(worktree).implementer;
+    const attemptId = crypto.randomUUID();
+    const reportPath = join(workspaceRoot, "metrics", slug, `.attempt-${attemptId}.json`);
+    const fallbackAttempt = incompleteAttempt(attemptId, slug, number, selection);
     observe("dispatch metrics", () => recordDispatch(workspaceRoot, slug, number));
     await validateRoleSelection("implementer", selection, worktree);
-    console.log(roleSelectionSummary("implementer", selection));
 
     const plannerPane = string(process.env["HERDR_PANE_ID"], "HERDR_PANE_ID");
     const plannerProcesses = foregroundProcesses(paneProcessInfo(plannerPane));
@@ -592,6 +762,12 @@ export async function runCodeless(args: string[]): Promise<void> {
     }
     requirePaneShell(implementerPane, worktree);
 
+    const collection = JSON.stringify({
+      id: attemptId,
+      stream: slug,
+      change: number,
+      path: reportPath,
+    });
     const started = herdr([
       "agent",
       "start",
@@ -602,6 +778,10 @@ export async function runCodeless(args: string[]): Promise<void> {
       implementerPane,
       "--",
       "--no-session",
+      "--extension",
+      implementerReportingExtension,
+      "--codeless-attempt",
+      collection,
       "--name",
       `${slug}-impl`,
       ...roleSelectionArguments(selection),
@@ -618,7 +798,7 @@ export async function runCodeless(args: string[]): Promise<void> {
       throw new Error(`${implementerName} started in ${startedCwd}, expected ${worktree}`);
     }
 
-    const completed = run("herdr", [
+    run("herdr", [
       "agent",
       "prompt",
       implementerName,
@@ -627,7 +807,19 @@ export async function runCodeless(args: string[]): Promise<void> {
       "--timeout",
       "3600000",
     ]);
-    console.log(completed.trim());
+    let attempt = fallbackAttempt;
+    try {
+      attempt = collectedAttempt(JSON.parse(readFileSync(reportPath, "utf8")), fallbackAttempt);
+      if (attempt === fallbackAttempt) throw new Error("report did not match its dispatch attempt");
+    } catch (error) {
+      console.error(
+        `codeless: warning: could not collect implementer attempt: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    } finally {
+      if (existsSync(reportPath)) unlinkSync(reportPath);
+    }
+    observe("implementer attempt", () => recordAttempt(workspaceRoot, slug, number, attempt));
+    console.log(JSON.stringify(attempt));
   }
 
   async function launchPlanner(slug: string): Promise<void> {
@@ -785,6 +977,11 @@ export async function runCodeless(args: string[]): Promise<void> {
     }
   }
 
+  if (action === "init") {
+    if (target !== undefined || details.length > 0) throw new Error(usage);
+    init();
+    return;
+  }
   if (action === "metrics") {
     if (target !== undefined || details.length > 0) throw new Error(usage);
     for (const line of metricReport(workspaceRoot)) console.log(line);

package/src/metrics.ts

@@ -5,17 +5,21 @@ import {
   readFileSync,
   readdirSync,
   renameSync,
+  rmdirSync,
   unlinkSync,
   writeFileSync,
 } from "node:fs";
 import { dirname, join } from "node:path";
 
+import { type Attempt, validAttempt } from "./attempt.ts";
+
 export type Metric = {
   stream: string;
   change: string;
   dispatchedAt?: string;
   landedAt?: string;
   landedCommit?: string;
+  attempts?: Record<string, Attempt>;
 };
 
 function metricPath(workspaceRoot: string, stream: string, change: string): string {
@@ -32,7 +36,16 @@ function readMetric(path: string): Metric {
     typeof metric["change"] !== "string" ||
     (metric["dispatchedAt"] !== undefined && typeof metric["dispatchedAt"] !== "string") ||
     (metric["landedAt"] !== undefined && typeof metric["landedAt"] !== "string") ||
-    (metric["landedCommit"] !== undefined && typeof metric["landedCommit"] !== "string")
+    (metric["landedCommit"] !== undefined && typeof metric["landedCommit"] !== "string") ||
+    (metric["attempts"] !== undefined &&
+      (typeof metric["attempts"] !== "object" ||
+        metric["attempts"] === null ||
+        Array.isArray(metric["attempts"]) ||
+        !Object.entries(metric["attempts"] as Record<string, unknown>).every(
+          ([id, attempt]) =>
+            validAttempt(attempt, metric["stream"] as string, metric["change"] as string) &&
+            attempt.id === id,
+        )))
   )
     throw new Error(`${path} is not a metric record`);
   return metric as Metric;
@@ -73,6 +86,50 @@ export function recordDispatch(workspaceRoot: string, stream: string, change: st
   readMetric(path);
 }
 
+function withMetricLock(path: string, action: () => void): void {
+  const lock = `${path}.lock`;
+  mkdirSync(dirname(path), { recursive: true });
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    try {
+      mkdirSync(lock);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      Bun.sleepSync(10);
+      continue;
+    }
+    try {
+      action();
+    } finally {
+      rmdirSync(lock);
+    }
+    return;
+  }
+  throw new Error(`could not acquire metric lock ${lock}`);
+}
+
+export function recordAttempt(
+  workspaceRoot: string,
+  stream: string,
+  change: string,
+  attempt: Attempt,
+): void {
+  if (!validAttempt(attempt, stream, change))
+    throw new Error("attempt is not a valid metric attempt");
+  const path = metricPath(workspaceRoot, stream, change);
+  withMetricLock(path, () => {
+    const metric = existsSync(path) ? readMetric(path) : { stream, change };
+    if (metric.stream !== stream || metric.change !== change)
+      throw new Error(`${path} does not match ${stream} change ${change}`);
+    const existing = metric.attempts?.[attempt.id];
+    if (existing !== undefined) {
+      if (JSON.stringify(existing) !== JSON.stringify(attempt))
+        throw new Error(`attempt ${attempt.id} conflicts with its existing metric record`);
+      return;
+    }
+    writeMetric(path, { ...metric, attempts: { ...metric.attempts, [attempt.id]: attempt } });
+  });
+}
+
 export function recordLanding(
   workspaceRoot: string,
   stream: string,