@tduyng/pi-autoresearch 0.0.1 → 0.0.3

package/README.md

@@ -1,45 +1,37 @@
 # @tduyng/pi-autoresearch
 
-An autonomous experiment loop for pi that costs nothing until you type `/autoresearch`.
-Two tools and one log. The model reads the benchmark, decides keep or discard, and the tools do the
-bookkeeping: commit, revert, scope, script hash, noise floor, and one line of context back.
+An experiment loop you turn on with one command. Measure, read the number, keep or discard, and let the tools handle git, scope, and the noise floor.
 
-## Cold start
+## What it costs
 
-Nothing is registered at load: no tool, no skill, no system prompt block. The extension adds one slash
-command. The tools are registered and declared to the model only when `/autoresearch` runs, and removed on
-`off`, `clear`, or when `max_runs` is reached.
+Nothing at cold start. No tool, no skill, no system prompt block: the extension adds one slash command, and that is free until typed. The two tools are declared to the model only while `/autoresearch` runs, and removed on `off`, `clear`, or when `max_runs` is reached.
+
+The saving is the second half of every optimization loop. Editing a benchmark, committing a regression, and re-reading a whole log by hand are the parts that cost turns, and all three are one line of bookkeeping here.
 
 ## The loop
 
-```
+```text
 edit -> run_experiment -> read the output -> log_experiment -> repeat
 ```
 
-`run_experiment` snapshots the working tree, runs `.auto/measure.sh`, parses `METRIC name=value` lines, runs
-the optional checks, and returns the output, the metrics, the changed files, the noise advice, and the
-scope violations. It does not touch git history.
+`run_experiment` snapshots the working tree, runs `.auto/measure.sh`, parses `METRIC name=value` lines, runs the optional checks, and returns the output, the metrics, the changed files, the noise advice, and the scope violations. It does not touch git history.
 
-`log_experiment` takes `status: keep | discard | crash | checks_failed` and the model's reasoning in `asi`.
-A `keep` commits the files the run touched with a conventional subject built from the description. Every
-other status restores those files. A run inside the noise band, a crash, or a scope violation is reported,
-not auto-decided: the model chooses.
+`log_experiment` takes `status: keep | discard | crash | checks_failed` and the model's reasoning in `asi`. A `keep` commits the files the run touched with a conventional subject built from the description. Every other status restores those files. A run inside the noise band, a crash, or a scope violation is reported rather than decided, because a rule cannot know whether the diff caused the gain.
 
 ## What it adds over the usual loop
 
 | Mechanism | Why |
 | --- | --- |
-| Model owns keep or discard | a rule cannot know whether the diff caused the gain, or whether simpler code is worth 1% |
-| Full benchmark output | phase timings and errors reach the model, so the next hypothesis comes from data |
-| Noise floor from median absolute deviation | advice that separates jitter from a real win; confidence never overrides the model |
-| Pending measurement | one run between the two tools, crash-safe on disk, so a restart can still log it |
-| Scope globs in frontmatter | a keep cannot touch files outside the declared scope |
-| Benchmark script hash | editing the benchmark to move the number voids the comparison; `/autoresearch rebaseline` starts a new segment |
-| Worktree lock and dirty baseline | one loop per worktree, and files another session left dirty are never committed or reverted |
-| Finalize in temporary worktrees | kept runs become branches without moving HEAD under another session |
-| Compaction digest from disk | the prompt body, recent runs, dead ends and ideas survive a context reset, no LLM call |
-| Conventional commits | `type(scope): summary`, at most 72 characters, one `Metric:` trailer, built by the tool from validated parts |
-| Lazy tool registration | zero tokens at cold start |
+| Model owns keep or discard | A rule cannot tell whether 1% came from the diff, or whether simpler code is worth 1% |
+| Full benchmark output | Phase timings and errors reach the model, so the next hypothesis comes from data |
+| Noise floor from median absolute deviation | Advice that separates jitter from a real win, and confidence never overrides the model |
+| Pending measurement | One run between the tools, crash-safe on disk, so a restart can still log it |
+| Scope globs in frontmatter | A keep cannot touch files outside the declared scope |
+| Benchmark script hash | Editing the benchmark to move the number voids the comparison |
+| Worktree lock and dirty baseline | One loop per worktree, and files another session left dirty are never committed |
+| Finalize in temporary worktrees | Kept runs become branches without moving HEAD under another session |
+| Compaction digest from disk | Prompt, recent runs, dead ends, and ideas survive a reset with no model call |
+| Conventional commits | `type(scope): summary`, at most 72 characters, one `Metric:` trailer, built from validated parts |
 
 ## Files
 
@@ -64,48 +56,47 @@ What is optimized, the constraints, and what a good change looks like.
 
 | File | Purpose |
 | --- | --- |
-| `.auto/prompt.md` | frontmatter config plus the objective and what has been tried |
-| `.auto/measure.sh` | benchmark, prints `METRIC name=value` |
-| `.auto/log.jsonl` | append-only record |
-| `.auto/checks.sh` | optional correctness checks, run after a passing benchmark |
-| `.auto/ideas.md` | optional backlog of ideas not tried yet |
-| `.auto/pending.json` | the run waiting for a decision |
-| `.auto/lock.json` | the session that owns this worktree |
+| `.auto/prompt.md` | Frontmatter config, the objective, and what has been tried |
+| `.auto/measure.sh` | The benchmark, printing `METRIC name=value` |
+| `.auto/log.jsonl` | Append-only record |
+| `.auto/checks.sh` | Optional correctness checks, run after a passing benchmark |
+| `.auto/ideas.md` | Optional backlog of ideas not tried |
+| `.auto/pending.json` | The run waiting for a decision |
+| `.auto/lock.json` | The session that owns this worktree |
 
-`.auto/` is added to the repository's common `.git/info/exclude` on the first run, so none of it lands in a
-commit, including from a linked worktree.
+`.auto/` is added to the repository's `.git/info/exclude` on the first run, including from a linked worktree, so none of it lands in a commit.
 
-Run it in an interactive pi session or through RPC. `pi -p` exits as soon as the slash command returns,
-before the loop's first turn, so a print run cannot drive the loop.
+Run it in an interactive session or through RPC. `pi -p` exits as soon as the slash command returns, before the loop's first turn, so a print run cannot drive it.
 
 ## Commands
 
 | Command | Effect |
 | --- | --- |
-| `/autoresearch <goal>` | start a session, or resume the one in `.auto/` |
-| `/autoresearch status` | print the digest |
-| `/autoresearch off` | stop and remove the tools |
-| `/autoresearch rebaseline` | accept a changed benchmark script as a new baseline |
-| `/autoresearch finalize` | split kept runs into independent branches from the merge-base |
-| `/autoresearch clear` | delete the log and stop |
+| `/autoresearch <goal>` | Start a session, or resume the one in `.auto/` |
+| `/autoresearch status` | Print the digest |
+| `/autoresearch off` | Stop and remove the tools |
+| `/autoresearch rebaseline` | Accept a changed benchmark script as a new baseline |
+| `/autoresearch finalize` | Split kept runs into independent branches from the merge-base |
+| `/autoresearch clear` | Delete the log and stop |
 
-`finalize` groups kept runs by file overlap and creates one branch per group from the merge-base in
-temporary worktrees. The current worktree is never checked out to another branch. It verifies that the
-union of the branches matches the original branch before reporting.
+`finalize` groups kept runs by file overlap and creates one branch per group from the merge-base in temporary worktrees. The current worktree is never checked out to another branch, and the union of the branches is verified against the original before it reports.
 
 ## Worktrees and other sessions
 
-One loop owns a worktree at a time. `/autoresearch` takes `.auto/lock.json`, and a second session in the same
-worktree is refused before it can run anything. Files that were already dirty when the loop started are
-recorded in the lock and never committed or reverted.
+One loop owns a worktree at a time: `/autoresearch` takes `.auto/lock.json` and refuses a second session before it can run anything. Files that were already dirty when the loop started are recorded in the lock and never committed or reverted.
 
-For a second loop on the same repository, use a separate git worktree. Each worktree has its own `.auto/`,
-its own branch, and its own log. The first run creates `autoresearch/<name>-<timestamp>` when you are on
-trunk and leaves an existing feature branch alone.
+For a second loop, use a separate git worktree, which gets its own `.auto/`, branch, and log. The first run on trunk creates `autoresearch/<name>-<timestamp>` in a worktree at `~/worktrees/<repo>/autoresearch-<name>-<timestamp>` and leaves the shared checkout on trunk. An existing feature branch is used as it is.
 
 ## Compaction and restarts
 
-While the loop is active, `session_before_compact` replaces pi's LLM summary with a deterministic digest
-built from `.auto/`: the prompt body, the recent runs, kept runs, dead ends, ideas, and any pending
-measurement. After a restart of the same session, the loop re-arms from the session's activation entry and
-sends one short resume message. A fresh session never auto-activates.
+While the loop is active, `session_before_compact` replaces pi's model summary with a deterministic digest built from `.auto/`: the prompt body, recent runs, kept runs, dead ends, ideas, and any pending measurement. No model call, no lost history.
+
+After a restart of the same session the loop re-arms from the session's activation entry and sends one short resume message. A fresh session never auto-activates.
+
+## Install
+
+```bash
+pi install npm:@tduyng/pi-autoresearch
+```
+
+Local checkout: `pi install /path/to/dotfiles/pi/agent/extensions/pi-autoresearch`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tduyng/pi-autoresearch",
-  "version": "0.0.1",
-  "description": "Autonomous experiment loop with zero cold-start cost: measure, decide, commit or revert, with scope and benchmark guards.",
+  "version": "0.0.3",
+  "description": "Autonomous experiment loop that costs nothing until you type /autoresearch: measure, decide, commit or revert, with scope and benchmark guards.",
   "keywords": [
     "pi",
     "pi-package",

package/src/experiment.ts

@@ -1,10 +1,7 @@
 import { randomUUID } from 'node:crypto'
+import { readFileSync } from 'node:fs'
 
-import type {
-    AgentToolResult,
-    AgentToolUpdateCallback,
-    ExtensionContext
-} from '@earendil-works/pi-coding-agent'
+import type { AgentToolResult, AgentToolUpdateCallback, ExtensionContext } from '@earendil-works/pi-coding-agent'
 import { t } from 'ata-validator/t'
 
 import { runCommand } from './command.js'
@@ -61,13 +58,10 @@ const CHECKS_TAIL_LINES = 8
 const PENDING_TTL_MS = 24 * 60 * 60 * 1000
 const FILE_LIST_LIMIT = 10
 
-const AsiParam = t.record(t.union([t.string(), t.number(), t.boolean(), t.null()])
-)
+const AsiParam = t.record(t.union([t.string(), t.number(), t.boolean(), t.null()]))
 
 const RunParams = t.object({
-    command: t.optional(
-        t.string({ description: 'Benchmark command to run instead of the one in .auto/prompt.md' })
-    ),
+    command: t.optional(t.string({ description: 'Benchmark command to run instead of the one in .auto/prompt.md' })),
     timeout_seconds: t.optional(t.number({ description: 'Kill the benchmark after this many seconds' }))
 })
 
@@ -80,9 +74,7 @@ const LogParams = t.object({
     description: t.string({
         description: 'One imperative line naming the change, in the words of a commit subject ("use forks pool").'
     }),
-    asi: t.optional(
-        AsiParam
-    ),
+    asi: t.optional(AsiParam),
     note: t.optional(t.string({ description: 'One line of what this run taught you. Shorthand for asi.note.' }))
 })
 
@@ -187,11 +179,7 @@ export function outOfScope(files: readonly string[], scope: readonly string[]):
     return files.filter((file) => !patterns.some((pattern) => pattern.test(file)))
 }
 
-function primaryMetric(
-    samples: readonly PendingSample[],
-    config: ResearchConfig,
-    seconds: number
-): number | null {
+function primaryMetric(samples: readonly PendingSample[], config: ResearchConfig, seconds: number): number | null {
     const parsed = metricValue(samples, config.metric)
     if (parsed !== null) return parsed
     if (config.metric === 'duration' || config.metric === 'seconds') return seconds
@@ -274,42 +262,35 @@ async function executeRun(
         output: result.output,
         tail: result.tail,
         fullOutputPath: result.fullOutputPath,
-        metrics: parseMetricLines(result.output)
+        metrics: parseMetricLines(
+            result.fullOutputPath === null ? result.output : readFileSync(result.fullOutputPath, 'utf8')
+        )
     }
 }
 
-async function runChecks(
-    pi: GitApi,
-    cwd: string,
-    signal: AbortSignal | undefined
-): Promise<ChecksOutcome | null> {
+async function runChecks(pi: GitApi, cwd: string, signal: AbortSignal | undefined): Promise<ChecksOutcome | null> {
     const path = checksPath(cwd)
     if (!fileExists(path)) return null
-    const result = await pi.exec('bash', [path], {
-        cwd,
-        timeout: CHECKS_TIMEOUT_SECONDS * 1000,
-        signal
-    }).catch(() => ({ stdout: '', stderr: 'checks could not run', code: 1, killed: false }))
-    const tail = `${result.stdout}\n${result.stderr}`
-        .trim()
-        .split('\n')
-        .slice(-CHECKS_TAIL_LINES)
-        .join('\n')
+    const result = await pi
+        .exec('bash', [path], {
+            cwd,
+            timeout: CHECKS_TIMEOUT_SECONDS * 1000,
+            signal
+        })
+        .catch(() => ({ stdout: '', stderr: 'checks could not run', code: 1, killed: false }))
+    const tail = `${result.stdout}\n${result.stderr}`.trim().split('\n').slice(-CHECKS_TAIL_LINES).join('\n')
     return { passed: result.code === 0 && !result.killed, tail }
 }
 
-function secondarySummary(
-    state: LogState,
-    samples: readonly PendingSample[],
-    config: ResearchConfig
-): string | null {
+function secondarySummary(state: LogState, samples: readonly PendingSample[], config: ResearchConfig): string | null {
     const extras = samples.filter((sample) => sample.name !== config.metric).slice(0, 4)
     if (extras.length === 0) return null
     const baseline = runsInSegment(state)[0]?.metrics ?? {}
     return extras
         .map((sample) => {
             const reference = baseline[sample.name]
-            const delta = reference === undefined || reference === 0 ? '' : ` (${formatPercent(sample.value, reference)})`
+            const delta =
+                reference === undefined || reference === 0 ? '' : ` (${formatPercent(sample.value, reference)})`
             return `${sample.name} ${formatMetric(sample.value, inferUnit(sample.name))}${delta}`
         })
         .join(' | ')
@@ -365,7 +346,7 @@ export function createRunTool(pi: GitApi, hooks: ExperimentHooks) {
         promptSnippet: 'Run the benchmark once and show the measurement',
         promptGuidelines: [
             'Run this after editing files and before log_experiment. It never changes git history.',
-            'Read the benchmark output, the secondary metrics and the noise advice before deciding. The decision is yours, not the tool\'s.',
+            "Read the benchmark output, the secondary metrics and the noise advice before deciding. The decision is yours, not the tool's.",
             'If a run is already pending, call log_experiment first. One pending run at a time.'
         ],
         parameters: RunParams,
@@ -531,6 +512,20 @@ export function createLogTool(pi: GitApi, hooks: ExperimentHooks) {
             const cwd = ctx.cwd
             const setup = sessionSetup(cwd)
             if (setup.kind === 'error') return errorResult(setup.message)
+            const lockProblem = ensureLock(ctx)
+            if (lockProblem !== null) return errorResult(lockProblem)
+            const activeLock = readLock(cwd)
+            const current = await git.currentBranch(pi, cwd)
+            if (
+                activeLock !== null &&
+                activeLock.branch.length > 0 &&
+                current.length > 0 &&
+                current !== activeLock.branch
+            ) {
+                return errorResult(
+                    `The worktree moved from ${activeLock.branch} to ${current}. Check out ${activeLock.branch} before logging a keep.`
+                )
+            }
             const config = setup.config
             const pending = readPending(cwd)
             if (pending === null) {

package/src/git.ts

@@ -85,24 +85,14 @@ export async function stagePaths(pi: GitApi, cwd: string, files: readonly string
     return git(pi, cwd, ['add', '--', ...files])
 }
 
-export async function commitStaged(
-    pi: GitApi,
-    cwd: string,
-    subject: string,
-    body: string
-): Promise<CommitResult> {
+export async function commitStaged(pi: GitApi, cwd: string, subject: string, body: string): Promise<CommitResult> {
     const result = await git(pi, cwd, ['commit', '-m', subject, '-m', body])
     if (result.code !== 0) return { sha: '', output: result.output }
     const sha = await git(pi, cwd, ['rev-parse', '--short=7', 'HEAD'])
     return sha.code === 0 ? { sha: sha.output, output: '' } : { sha: '', output: sha.output }
 }
 
-export async function commitAllowEmpty(
-    pi: GitApi,
-    cwd: string,
-    subject: string,
-    body: string
-): Promise<GitResult> {
+export async function commitAllowEmpty(pi: GitApi, cwd: string, subject: string, body: string): Promise<GitResult> {
     return git(pi, cwd, ['commit', '--allow-empty', '-m', subject, '-m', body])
 }
 
@@ -130,8 +120,15 @@ export async function restoreFiles(pi: GitApi, cwd: string, files: readonly Pend
     return failure
 }
 
-export async function createBranch(pi: GitApi, cwd: string, name: string): Promise<GitResult> {
-    return git(pi, cwd, ['checkout', '-b', name])
+export async function repoName(pi: GitApi, cwd: string): Promise<string> {
+    const origin = await git(pi, cwd, ['remote', 'get-url', 'origin'])
+    if (origin.code === 0 && origin.output.length > 0) return path.basename(origin.output).replace(/\.git$/, '')
+    const top = await git(pi, cwd, ['rev-parse', '--show-toplevel'])
+    return path.basename(top.output)
+}
+
+export function loopWorktreePath(repo: string, branch: string): string {
+    return path.join(os.homedir(), 'worktrees', repo, branch.replace(/\//g, '-'))
 }
 
 export async function branchExists(pi: GitApi, cwd: string, name: string): Promise<boolean> {
@@ -154,12 +151,8 @@ export async function mergeBase(pi: GitApi, cwd: string, trunk: string): Promise
 }
 
 export async function filesInCommit(pi: GitApi, cwd: string, commit: string): Promise<readonly string[]> {
-    const result = await git(pi, cwd, ['show', '--name-only', '--format=', commit])
-    if (result.code !== 0) return []
-    return result.output
-        .split('\n')
-        .map((line) => line.trim())
-        .filter((line) => line.length > 0 && !line.startsWith(`${RESEARCH_DIRECTORY}/`))
+    const files = await zeroList(pi, cwd, ['show', '--name-only', '--format=', commit])
+    return files.filter((file) => !file.startsWith(`${RESEARCH_DIRECTORY}/`))
 }
 
 export async function fileInCommit(pi: GitApi, cwd: string, commit: string, file: string): Promise<boolean> {

package/src/index.ts

@@ -229,8 +229,10 @@ export default function autoresearchExtension(pi: ExtensionAPI): void {
         }
         if (branch.length > 0 && branch !== trunk) return null
         const name = `autoresearch/${slugify(config?.name ?? goal, 30)}-${branchStamp()}`
-        const created = await git.createBranch(pi, ctx.cwd, name)
-        return created.code === 0 ? null : `Could not create branch ${name}: ${created.output}`
+        const directory = git.loopWorktreePath(await git.repoName(pi, ctx.cwd), name)
+        const created = await git.worktreeAddBranch(pi, ctx.cwd, directory, name, 'HEAD')
+        if (created.code !== 0) return `Could not create branch ${name}: ${created.output}`
+        return `Autoresearch runs in its own worktree: ${directory}. This checkout stays on ${branch}. Start pi in that directory and run /autoresearch there.`
     }
 
     const activate = async (ctx: ExtensionCommandContext, text: string): Promise<void> => {

package/src/session.ts

@@ -29,9 +29,7 @@ const isLockSchema = new Validator(LockSchema).isValidObject
 
 export type SessionLock = Infer<typeof LockSchema>
 
-export type LockResult =
-    | { kind: 'ok'; lock: SessionLock }
-    | { kind: 'other'; lock: SessionLock }
+export type LockResult = { kind: 'ok'; lock: SessionLock } | { kind: 'other'; lock: SessionLock }
 
 export function researchPath(cwd: string, file: string): string {
     return path.join(cwd, RESEARCH_DIRECTORY, file)
@@ -143,12 +141,18 @@ function writeLock(cwd: string, lock: SessionLock): void {
     fs.renameSync(temporary, target)
 }
 
-export function acquireLock(
-    cwd: string,
-    sessionId: string,
-    branch: string,
-    dirty: readonly string[]
-): LockResult {
+function createLock(cwd: string, lock: SessionLock): boolean {
+    const directory = path.join(cwd, RESEARCH_DIRECTORY)
+    fs.mkdirSync(directory, { recursive: true })
+    try {
+        fs.writeFileSync(lockPath(cwd), `${JSON.stringify(lock)}\n`, { flag: 'wx' })
+        return true
+    } catch {
+        return false
+    }
+}
+
+export function acquireLock(cwd: string, sessionId: string, branch: string, dirty: readonly string[]): LockResult {
     const existing = readLock(cwd)
     if (existing !== null && existing.sessionId !== sessionId && pidAlive(existing.pid)) {
         return { kind: 'other', lock: existing }
@@ -161,8 +165,18 @@ export function acquireLock(
         startedAt: sameSession ? existing.startedAt : Date.now(),
         dirty: sameSession ? existing.dirty : [...dirty]
     }
-    writeLock(cwd, lock)
-    return { kind: 'ok', lock }
+    if (sameSession) {
+        writeLock(cwd, lock)
+        return { kind: 'ok', lock }
+    }
+    if (createLock(cwd, lock)) return { kind: 'ok', lock }
+    const latest = readLock(cwd)
+    if (latest !== null && latest.sessionId !== sessionId && pidAlive(latest.pid)) {
+        return { kind: 'other', lock: latest }
+    }
+    fs.rmSync(lockPath(cwd), { force: true })
+    if (createLock(cwd, lock)) return { kind: 'ok', lock }
+    return { kind: 'other', lock: readLock(cwd) ?? lock }
 }
 
 export function releaseLock(cwd: string, sessionId: string): void {