@tduyng/pi-autoresearch 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,178 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+Use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+(a) You must give any other recipients of the Work or
+Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+that You distribute, all copyright, patent, trademark, and
+attribution notices from the Source form of the Work,
+excluding those notices that do not pertain to any part of
+the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+distribution, then any Derivative Works that You distribute must
+include a readable copy of the attribution notices contained
+within such NOTICE file, excluding those notices that do not
+pertain to any part of the Derivative Works, in at least one
+of the following places: within a NOTICE text file distributed
+as part of the Derivative Works; within the Source form or
+documentation, if provided along with the Derivative Works; or,
+within a display generated by the Derivative Works, if and
+wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and
+do not modify the License. You may add Your own attribution
+notices within Derivative Works that You distribute, alongside
+or as an addendum to the NOTICE text from the Work, provided
+that such additional attribution notices cannot be construed
+as modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+Copyright 2026 tduyng

package/README.md

@@ -1,3 +1,111 @@
-# Temporary Holding Version
+# @tduyng/pi-autoresearch
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+## Cold start
+
+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.
+
+## The loop
+
+```
+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.
+
+`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.
+
+## 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 |
+
+## Files
+
+`.auto/prompt.md` carries the frontmatter and the objective:
+
+```markdown
+---
+name: vitest startup
+metric: total_ms
+unit: ms
+direction: lower
+command: bash .auto/measure.sh
+scope: [vitest.config.ts, test/**]
+max_runs: 40
+min_gain: 0.5
+---
+
+What is optimized, the constraints, and what a good change looks like.
+```
+
+`min_gain` is the smallest relative improvement the advice treats as real, in percent. It never blocks a keep.
+
+| 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/` 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.
+
+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.
+
+## 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 |
+
+`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.
+
+## 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.
+
+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.
+
+## 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.

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@tduyng/pi-autoresearch",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "Autonomous experiment loop with zero cold-start cost: measure, decide, commit or revert, with scope and benchmark guards.",
+  "keywords": [
+    "pi",
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "autoresearch",
+    "experiment",
+    "optimization",
+    "benchmark"
+  ],
+  "homepage": "https://gitlab.com/tduyng/pi-agent/-/tree/main/extensions/pi-autoresearch#readme",
+  "bugs": "https://gitlab.com/tduyng/pi-agent/-/issues",
+  "license": "Apache-2.0",
+  "author": "tduyng",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/tduyng/pi-agent.git",
+    "directory": "extensions/pi-autoresearch"
+  },
+  "type": "module",
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "dependencies": {
+    "ata-validator": "^1.62.1"
+  }
+}

package/src/command.ts

@@ -0,0 +1,158 @@
+import { spawn } from 'node:child_process'
+import { randomBytes } from 'node:crypto'
+import * as fs from 'node:fs'
+import { tmpdir } from 'node:os'
+import * as path from 'node:path'
+
+const RETAINED_BYTES = 128 * 1024
+const TEMP_FILE_THRESHOLD_BYTES = 128 * 1024
+const TEMP_FILE_LIMIT_BYTES = 20 * 1024 * 1024
+const TAIL_LINES = 40
+const TICK_MS = 5000
+
+export interface CommandResult {
+    exitCode: number | null
+    timedOut: boolean
+    seconds: number
+    output: string
+    tail: string
+    totalBytes: number
+    fullOutputPath: string | null
+}
+
+export interface CommandOptions {
+    cwd: string
+    timeoutSeconds: number
+    signal: AbortSignal | undefined
+    onTick: ((seconds: number) => void) | undefined
+}
+
+interface Capture {
+    chunks: Buffer[]
+    retainedBytes: number
+    totalBytes: number
+    fullOutputPath: string | null
+    stream: fs.WriteStream | null
+}
+
+function killTree(pid: number): void {
+    try {
+        process.kill(-pid, 'SIGTERM')
+    } catch {
+        try {
+            process.kill(pid, 'SIGTERM')
+        } catch {
+            return
+        }
+    }
+}
+
+function tempFilePath(): string {
+    return path.join(tmpdir(), `pi-autoresearch-${randomBytes(6).toString('hex')}.log`)
+}
+
+function retain(capture: Capture, data: Buffer): void {
+    capture.chunks.push(data)
+    capture.retainedBytes += data.length
+    while (capture.retainedBytes > RETAINED_BYTES && capture.chunks.length > 1) {
+        const removed = capture.chunks.shift()
+        if (removed === undefined) break
+        capture.retainedBytes -= removed.length
+    }
+}
+
+function startStream(capture: Capture): void {
+    capture.fullOutputPath = tempFilePath()
+    capture.stream = fs.createWriteStream(capture.fullOutputPath)
+    for (const chunk of capture.chunks) capture.stream.write(chunk)
+}
+
+function writeFull(capture: Capture, data: Buffer): void {
+    if (capture.stream === null) return
+    if (capture.totalBytes > TEMP_FILE_LIMIT_BYTES) return
+    capture.stream.write(data)
+}
+
+function captureData(capture: Capture, data: Buffer): void {
+    capture.totalBytes += data.length
+    if (capture.stream === null && capture.totalBytes > TEMP_FILE_THRESHOLD_BYTES) startStream(capture)
+    writeFull(capture, data)
+    retain(capture, data)
+}
+
+function tailOf(text: string): string {
+    return text.split('\n').slice(-TAIL_LINES).join('\n').trim()
+}
+
+export function runCommand(command: string, options: CommandOptions): Promise<CommandResult> {
+    return new Promise<CommandResult>((resolve, reject) => {
+        const started = Date.now()
+        const capture: Capture = {
+            chunks: [],
+            retainedBytes: 0,
+            totalBytes: 0,
+            fullOutputPath: null,
+            stream: null
+        }
+        let timedOut = false
+        const child = spawn('bash', ['-c', command], {
+            cwd: options.cwd,
+            detached: true,
+            stdio: ['ignore', 'pipe', 'pipe']
+        })
+
+        const finishStream = (): void => {
+            if (capture.stream !== null) capture.stream.end()
+        }
+
+        const tick = setInterval(() => {
+            if (options.onTick === undefined) return
+            options.onTick((Date.now() - started) / 1000)
+        }, TICK_MS)
+
+        const timeout =
+            options.timeoutSeconds > 0
+                ? setTimeout(() => {
+                      timedOut = true
+                      if (child.pid !== undefined) killTree(child.pid)
+                  }, options.timeoutSeconds * 1000)
+                : null
+
+        const onAbort = (): void => {
+            if (child.pid !== undefined) killTree(child.pid)
+            else child.kill()
+        }
+
+        if (options.signal !== undefined) {
+            if (options.signal.aborted) onAbort()
+            else options.signal.addEventListener('abort', onAbort, { once: true })
+        }
+
+        child.stdout?.on('data', (data: Buffer) => captureData(capture, data))
+        child.stderr?.on('data', (data: Buffer) => captureData(capture, data))
+
+        child.on('error', (error: Error) => {
+            clearInterval(tick)
+            if (timeout !== null) clearTimeout(timeout)
+            finishStream()
+            reject(error)
+        })
+
+        child.on('close', (code: number | null) => {
+            clearInterval(tick)
+            if (timeout !== null) clearTimeout(timeout)
+            if (options.signal !== undefined) options.signal.removeEventListener('abort', onAbort)
+            finishStream()
+            const text = Buffer.concat(capture.chunks).toString('utf8')
+            resolve({
+                exitCode: code,
+                timedOut,
+                seconds: (Date.now() - started) / 1000,
+                output: text,
+                tail: tailOf(text),
+                totalBytes: capture.totalBytes,
+                fullOutputPath: capture.fullOutputPath
+            })
+        })
+    })
+}

package/src/digest.ts

@@ -0,0 +1,136 @@
+import type { ResearchConfig } from './frontmatter.js'
+import {
+    baselineMetric,
+    bestMetric,
+    confidence,
+    deadEndHypotheses,
+    lastRun,
+    noiseFloor,
+    runsInSegment,
+    runsWithoutGain,
+    type LogState,
+    type Run
+} from './log.js'
+import { formatMetric, formatPercent, truncateAtWord } from './format.js'
+
+const MAX_DIGEST_CHARS = 5000
+const KEPT_LIMIT = 5
+const DEAD_END_LIMIT = 15
+const RECENT_LIMIT = 24
+const LINE_LIMIT = 80
+const BODY_LIMIT = 1400
+const IDEAS_LIMIT = 800
+
+export interface DigestExtras {
+    body?: string
+    ideas?: string
+    pending?: boolean
+}
+
+function counts(state: LogState): string {
+    const runs = runsInSegment(state)
+    const kept = runs.filter((run) => run.status === 'keep').length
+    const crashed = runs.filter((run) => run.status === 'crash' || run.status === 'checks_failed').length
+    const discarded = runs.length - kept - crashed
+    const parts = [`${kept} keep`, `${discarded} discard`]
+    if (crashed > 0) parts.push(`${crashed} crash`)
+    return parts.join(', ')
+}
+
+function runLine(run: Run, baseline: number | null, unit: string): string {
+    const delta = baseline === null ? '' : ` ${formatPercent(run.metric, baseline)}`
+    return `#${run.run} ${run.status} ${formatMetric(run.metric, unit)}${delta} ${truncateAtWord(run.description, LINE_LIMIT)}`
+}
+
+function keptRuns(state: LogState): readonly Run[] {
+    const kept = runsInSegment(state).filter((run) => run.status === 'keep')
+    return kept.slice(-KEPT_LIMIT).toReversed()
+}
+
+function recentRuns(state: LogState): readonly Run[] {
+    return runsInSegment(state).slice(-RECENT_LIMIT)
+}
+
+function deadEndLine(state: LogState): string {
+    const hypotheses = deadEndHypotheses(state, DEAD_END_LIMIT).map((hypothesis) =>
+        truncateAtWord(hypothesis, LINE_LIMIT)
+    )
+    return hypotheses.length === 0 ? 'none yet' : hypotheses.join(' | ')
+}
+
+export function buildDigest(
+    state: LogState,
+    config: ResearchConfig | null,
+    scriptChanged: boolean,
+    extras: DigestExtras = {}
+): string {
+    const unit = config?.unit ?? state.config?.metricUnit ?? ''
+    const metricName = config?.metric ?? state.config?.metricName ?? 'metric'
+    const direction = config?.direction ?? state.config?.bestDirection ?? 'lower'
+    const baseline = baselineMetric(state)
+    const best = bestMetric(state)
+    const floor = noiseFloor(state)
+    const score = confidence(state)
+    const runs = runsInSegment(state)
+    const last = lastRun(state)
+    const budget = config?.maxRuns ?? 0
+    const remaining = budget > 0 ? Math.max(0, budget - runs.length) : null
+
+    const lines = [
+        '# Autoresearch digest (generated from .auto, not an LLM summary)',
+        `goal: ${config?.name ?? state.config?.name ?? 'autoresearch'}`,
+        `metric: ${metricName} (${direction} is better) | baseline ${baseline === null ? '-' : formatMetric(baseline, unit)} | best ${best === null ? '-' : formatMetric(best, unit)}${best === null || baseline === null ? '' : ` (${formatPercent(best, baseline)})`}`,
+        `noise: ${floor === null ? 'not enough runs' : `+/-${formatMetric(floor, unit)}`} | confidence ${score === null ? '-' : `${score.toFixed(1)}x`} | benchmark script ${scriptChanged ? 'CHANGED since baseline' : 'unchanged'}`,
+        `runs: ${runs.length}${budget > 0 ? ` of ${budget} (${remaining} left)` : ''} | ${counts(state)}${extras.pending === true ? ' | a measurement is pending' : ''}`,
+        ''
+    ]
+    if (extras.body !== undefined && extras.body.trim().length > 0) {
+        lines.push(`rules and objective:\n${truncateAtWord(extras.body.trim(), BODY_LIMIT)}`, '')
+    }
+    if (extras.ideas !== undefined && extras.ideas.trim().length > 0) {
+        lines.push(`ideas not tried:\n${truncateAtWord(extras.ideas.trim(), IDEAS_LIMIT)}`, '')
+    }
+    lines.push(
+        `kept: ${keptRuns(state).map((run) => runLine(run, baseline, unit)).join(' | ') || 'none yet'}`,
+        `dead ends: ${deadEndLine(state)}`,
+        `recent runs:\n${recentRuns(state).map((run) => runLine(run, baseline, unit)).join('\n') || 'none'}`,
+        `last: ${last === null ? 'none' : runLine(last, baseline, unit)}`,
+        `you decide keep or discard. The noise floor and confidence are advice. Next: one hypothesis, edit, run_experiment, read the output, log_experiment.`
+    )
+    return lines.join('\n').slice(0, MAX_DIGEST_CHARS)
+}
+
+export function buildResumeMessage(state: LogState, pending: boolean): string {
+    if (pending) {
+        return 'A measured run is pending. Call log_experiment with keep or discard now, then continue the loop.'
+    }
+    const runs = runsInSegment(state)
+    if (runs.length === 0) {
+        return 'No baseline yet. Call run_experiment, read the output, then log_experiment with status keep.'
+    }
+    const best = bestMetric(state)
+    const unit = state.config?.metricUnit ?? ''
+    const stuck = runsWithoutGain(state)
+    const deadEnds = deadEndHypotheses(state, 4).map((hypothesis) => truncateAtWord(hypothesis, 50))
+    const head = `Next iteration: read .auto/prompt.md and the tail of .auto/log.jsonl if you lost context. One hypothesis, edit, run_experiment, then log_experiment with your decision.${best === null ? '' : ` Best ${formatMetric(best, unit)}.`}`
+    const hint =
+        stuck >= 5 && deadEnds.length > 0
+            ? ` ${stuck} runs without a gain. Change the mechanism, not the constant. Dead ends: ${deadEnds.join(', ')}. Read the source and profile before the next idea.`
+            : ''
+    return `${head}${hint}`
+}
+
+export function buildStatusLine(state: LogState, config: ResearchConfig | null): string {
+    const unit = config?.unit ?? state.config?.metricUnit ?? ''
+    const best = bestMetric(state)
+    const baseline = baselineMetric(state)
+    const runs = runsInSegment(state).length
+    const last = lastRun(state)
+    const parts = [`${runs} run${runs === 1 ? '' : 's'}`]
+    if (best !== null) {
+        parts.push(`best ${formatMetric(best, unit)}`)
+        if (baseline !== null && best !== baseline) parts.push(formatPercent(best, baseline))
+    }
+    if (last !== null) parts.push(`last ${last.status}`)
+    return `autoresearch: ${parts.join(' | ')}`
+}