tewip-ai 0.23.0 → 0.25.0

package/README.md

@@ -8,7 +8,7 @@ It works for every stack: Node.js (node:test, Jest, Vitest, Mocha), Python (pyte
 |---|---|
 | **Terminal** | `npm install -g tewip-ai`, then `tewip explain report.xml`, `tewip ci owner/repo --pr 12`, `tewip mcp` |
 | **VS Code, Cursor, Windsurf, VSCodium** | the Tewip extension ([download](https://github.com/hmamut39/tewip/releases/tag/vscode-0.5.0)): registers Tewip with the editor's AI assistant and adds six commands - explain a report, why CI failed on this branch, the risk review of your change, which flaky tests to quarantine, the security check, and what your corrections add up to |
-| **JetBrains, Claude, other AI assistants** | add the MCP server `tewip mcp` (see [editor setup](#use-it-from-your-editor-any-ide-that-speaks-mcp)) |
+| **JetBrains, Claude, other AI assistants** | add the MCP server `tewip mcp`: fifteen tools, including *has this happened here before?*, *is this requirement covered and passing?* and *what should be done next about this goal?* (see [editor setup](#use-it-from-your-editor-any-ide-that-speaks-mcp)) |
 | **Any model** | OpenAI, Claude, Gemini, Azure, or a model on your own machine with Ollama (no account, nothing leaves the computer): `TEWIP_PROVIDER` |
 | **GitHub CI** | the Tewip Action: a comment on every pull request, an optional merge gate, verified fix PRs ([QUICKSTART](QUICKSTART.md)) |
 
@@ -71,6 +71,10 @@ On every run, the action:
 - **Developers:** posts one diagnosis comment on the pull request and keeps it updated. For each failure it says whether the change likely caused it, why, and what to do next.
 - **SDETs:** writes the triage board into the job summary.
 - **DevOps:** collects environment failures (server errors, connection resets, outages) in **one** GitHub issue, and each new run adds a single grouped comment to it.
+- **Evidence, every run:** the Action writes an attestation into its artifact - the claims with
+  their evidence and which layer decided each, what Tewip **refused** to decide, and what it did
+  not check at all. Nothing enters it that Tewip did not verify itself, so a release decision can
+  be taken from it without opening CI.
 - **Fixes (`autofix: true`):** for drifted locators that the deterministic rule matched to a renamed element, it rewrites the locator, re-runs that test, and opens a separate pull request with the changes that passed. It never merges and never edits application code.
 - **Every role:** uploads all role views as the `tewip-report` artifact.
 - **When the job dies before any test runs** (an image that would not pull, a runner out of disk, a service container that never came up): it reads the failed job's log and names the cause, instead of leaving a red X with no explanation.
@@ -440,6 +444,80 @@ Every change is small (1 to 16 lines, median 4) and most are what the developers
 **No wrong fix was offered**: anything that could not be proved was thrown away and the file put
 back byte for byte.
 
+## One bundle a release manager can read (Phase 15)
+
+```bash
+tewip attest --out attestation.md
+```
+
+Everything Tewip knows about a build, in one file: which tests ran, what each failure was, which
+rule or which model decided it, **what it refused to decide**, and what it never looked at. The
+refusals are the point - a tool that never says "I could not tell" has nothing worth attesting,
+because every line it writes might be a guess.
+
+The bundle carries a digest, and an Ed25519 signature when you give it a key:
+
+```bash
+TEWIP_ATTEST_KEY=./private.pem tewip attest            # sign it
+tewip attest --verify attestation.json --key public.pem  # check it
+```
+
+A digest is not a signature and Tewip says so: without a key it tells you the bundle is undamaged,
+not that nobody edited it. Editing a claim out of a signed bundle makes verification fail and exit
+non-zero. Every CI run writes one of these automatically.
+
+## Is this incident covered by a test? (Phase 16)
+
+```bash
+tewip incident sentry-issue.json
+```
+
+Reads a Sentry payload, an OpenTelemetry span or a plain stack trace, finds the test that should
+have caught it, and answers with one of four verdicts: **reproduced**, **passed** (the test ran and
+did not catch it, which is worse news), **failed differently**, or **never ran**. It does not say
+"probably covered".
+
+## What did we decide about this last time? (Phase 17)
+
+```bash
+tewip recall "the login test that keeps flaking"
+```
+
+Every correction your team ever gave Tewip is kept. Ask, and it answers with your own decision from
+then, and says it was yours - not its. It never acts on a correction by itself.
+
+## From the ticket to the run (Phase 18)
+
+```bash
+tewip trace --only "SHOP-12"
+```
+
+Joins the test plans Tewip wrote to the tests that cover them and the runs that attempted them. A
+scenario counts as covered only when a real test can be named, and passing only when a real run
+attempted it; everything else says what is missing. No model, no cost.
+
+## A goal instead of a verb (Phases 19 and 21)
+
+```bash
+tewip pursue "keep the checkout flow green"
+tewip pursue "keep the checkout flow green" --act
+```
+
+Give Tewip a goal and it says what it would do next, and why, from what it can actually see. The
+order is fixed, published and testable - **not chosen by a model**: a real bug first, then the
+environment, then flakiness, then anything failing it cannot explain, then a coverage gap, and only
+then is the goal worth attesting. Deciding the same state twice gives the same answer.
+
+With `--act` it carries the decision out, and this is where the refusals matter most:
+
+- It **never does the work itself.** Each action is an existing command that already proves what it
+  changes - `write` keeps a test only when it passes *and* fails when broken.
+- **Two actions are on the allowlist**: write a missing test, and attest a green goal. Everything
+  else is refused by name. It will not work around a real bug.
+- **One action, then stop.** There is no unattended loop.
+- Everything it did or refused goes to `.tewip/actions.jsonl`, with the run that justified it.
+- It **will not repeat itself**: the same attempt is refused until a new run gives it new evidence.
+
 ## Where it has been tried
 
 | Project | How | Result |

package/dist/cli/help.js

@@ -105,8 +105,11 @@ Usage:
                                     green" - and it says what it would do next and why, from what
                                     it can actually see. The order is fixed and written down: a
                                     real bug first, then the environment, then flakiness, then a
-                                    coverage gap. It decides; it does not act unless you ask, and
-                                    even then only through the gates that prove a change.
+                                    coverage gap. It decides; it does not act unless you ask. With
+                                    --act it carries out the two safe ones - writing a missing test,
+                                    or attesting a green goal - by running the command that already
+                                    proves them. It will not touch a real bug, and it writes what it
+                                    did or refused to .tewip/actions.jsonl.
   tewip trace [--only "<ticket or title>"] [--out trace.md]
                                     Is this requirement covered, and is it passing right now? Joins
                                     the plans Tewip wrote to the tests that cover them and the runs
@@ -125,10 +128,14 @@ Usage:
                                     it fails for the incident's own reason. A test that passes, or
                                     fails its own way, is reported and thrown away.
   tewip attest [--run <id>] [--out attestation.md] [--json bundle.json]
+  tewip attest --verify <bundle.json> [--key <public.pem>]
                                     What Tewip checked for a build, as one artifact: the claims with
                                     their evidence and which layer decided each, what it refused to
                                     decide and why, and what it did not check at all. Nothing enters
-                                    it that Tewip did not verify itself. No model, no cost.
+                                    it that Tewip did not verify itself. Every bundle carries a
+                                    digest; set TEWIP_ATTEST_KEY to an ed25519 private key to sign
+                                    it too. --verify says what it checked and what that does not
+                                    establish - a digest means undamaged, not unedited. No cost.
   tewip mcp                         Serve Tewip over MCP (stdio) for an editor or AI assistant.
   tewip --version                   Print the version.
 

package/dist/cli/tewip.js

@@ -210,6 +210,15 @@ async function main() {
             return;
         }
         case 'attest': {
+            const verify = flag(args, 'verify');
+            if (verify) {
+                const { verifyAttestation } = await import('../engine/attest/attest-command.js');
+                const { ok, report } = verifyAttestation(verify, flag(args, 'key'));
+                console.log(report);
+                if (!ok)
+                    process.exitCode = 1;
+                return;
+            }
             const { runAttest } = await import('../engine/attest/attest-command.js');
             runAttest({ root: process.cwd(), name: flag(args, 'name'), runId: flag(args, 'run'), out: flag(args, 'out'), json: flag(args, 'json') });
             return;

package/dist/engine/attest/attest-command.js

@@ -1,9 +1,32 @@
 // `tewip attest`: the evidence for one run, as an artifact a build can carry.
-import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { datasetFiles, readJsonl, readTriageRecords } from '../../reporters/store.js';
 import { ENGINE_VERSION } from '../engine.js';
 import { attestRun, renderAttestation } from './attest.js';
+import { check } from './seal.js';
+/**
+ * Checks a bundle somebody was handed. It reports what the check establishes and, just as
+ * importantly, what it does not: a digest that matches proves the file is undamaged, and only a
+ * signature checked against a key says who made it.
+ */
+export function verifyAttestation(file, keyFile) {
+    const bundle = JSON.parse(readFileSync(resolve(file), 'utf8'));
+    const publicKey = keyFile ? readFileSync(resolve(keyFile), 'utf8') : undefined;
+    const checked = check(bundle, publicKey);
+    const ok = checked.contentMatches && checked.signature !== 'invalid';
+    const report = [
+        `# ${ok ? 'Checked' : 'Do not trust this bundle'}: ${file.split(/[\/]/).pop()}`,
+        '',
+        `Content matches its digest: ${checked.contentMatches ? 'yes' : 'NO'}`,
+        `Signature: ${checked.signature.replace(/-/g, ' ')}`,
+        '',
+        checked.says + '.',
+        '',
+        ...(checked.signature === 'no-key-given' ? ['Pass `--key <public.pem>` to check the signature itself.'] : []),
+    ].join(String.fromCharCode(10));
+    return { ok, report };
+}
 /** Everything Tewip kept for one project, newest run last. */
 function history(root, only) {
     const dir = join(root, '.tewip', 'history');
@@ -23,9 +46,18 @@ function history(root, only) {
 function whatWasChecked(records) {
     const checked = [];
     const notChecked = [];
-    checked.push('every failing test in the run was read, and each was given a cause or left undecided');
-    const byRules = records.filter((r) => r.diagnosis?.source === 'rules').length;
-    const byModel = records.filter((r) => r.diagnosis?.source === 'llm').length;
+    // Decided means settled: a rule that looked and could not say is a refusal, and counting it here
+    // would have a bundle claim more decisions than it lists claims.
+    const settledBy = (source) => records.filter((r) => {
+        const d = r.diagnosis;
+        return d?.source === source && d.category && d.category !== 'UNKNOWN';
+    }).length;
+    if (records.length === 0)
+        checked.push('every test in the run passed, so there was nothing to diagnose');
+    else
+        checked.push('every failing test in the run was read, and each was given a cause or left undecided');
+    const byRules = settledBy('rules');
+    const byModel = settledBy('llm');
     if (byRules > 0)
         checked.push(`${byRules} decided by deterministic rules (${ENGINE_VERSION}), which call no model and give the same answer every time`);
     if (byModel > 0)

package/dist/engine/attest/attest.js

@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs';
+import { seal } from './seal.js';
 const sourceOf = (record) => String(record.diagnosis?.source ?? '');
 /** The evidence line a person reads: the first thing the deciding layer actually said. */
 function evidenceOf(record) {
@@ -33,7 +35,7 @@ export function attestRun(project, run, records, { checked, notChecked, tool, en
             confidence: Number(diagnosis?.confidence ?? 0),
         });
     }
-    return {
+    const bundle = {
         project,
         commit: run.gitSha ?? '',
         runId: run.runId,
@@ -47,6 +49,22 @@ export function attestRun(project, run, records, { checked, notChecked, tool, en
         refusals,
         producedBy: { tool, engine, at: new Date().toISOString() },
     };
+    // Sealed last, over everything above: the digest is of the content, never of itself.
+    return { ...bundle, seal: seal(bundle, signingKey()) };
+}
+/** The Ed25519 private key to sign with, from TEWIP_ATTEST_KEY: a PEM, or a path to one. */
+function signingKey() {
+    const given = process.env.TEWIP_ATTEST_KEY?.trim();
+    if (!given)
+        return undefined;
+    if (given.includes('BEGIN'))
+        return given;
+    try {
+        return readFileSync(given, 'utf8');
+    }
+    catch (error) {
+        throw new Error(`TEWIP_ATTEST_KEY points at ${given}, which could not be read: ${error instanceof Error ? error.message : String(error)}`);
+    }
 }
 /** The bundle as a person reads it. The refusals are not hidden at the bottom; they are the point. */
 export function renderAttestation(a) {
@@ -84,6 +102,10 @@ export function renderAttestation(a) {
         lines.push(`- **${refusal.what}**`);
         lines.push(`  - Why: ${refusal.why}`);
     }
-    lines.push('', '---', '', `Produced by ${a.producedBy.tool} (${a.producedBy.engine}) at ${a.producedBy.at.slice(0, 19).replace('T', ' ')} UTC.`, 'Every claim above names the run it came from and the layer that decided it. This is a statement', 'about the checks listed under "what was checked" and nothing else.');
+    lines.push('', '---', '', `Produced by ${a.producedBy.tool} (${a.producedBy.engine}) at ${a.producedBy.at.slice(0, 19).replace('T', ' ')} UTC.`, a.seal?.signature
+        ? `Signed (${a.seal.algorithm}); digest ${a.seal.digest.slice(0, 16)}…. Check it with \`tewip attest --verify <bundle.json> --key <public.pem>\`.`
+        : a.seal
+            ? `Digest ${a.seal.digest.slice(0, 16)}…, which is not a signature: it shows the bundle is undamaged, not that nobody edited it. Set TEWIP_ATTEST_KEY to sign.`
+            : '', 'Every claim above names the run it came from and the layer that decided it. This is a statement', 'about the checks listed under "what was checked" and nothing else.');
     return lines.join('\n');
 }

package/dist/engine/attest/seal.js

@@ -0,0 +1,90 @@
+// Sealing an attestation, and being precise about what a seal is worth.
+//
+// The roadmap promised a "signed" bundle and the first implementation signed nothing. This closes
+// that, but the honest part is the distinction it refuses to blur:
+//
+//   A **digest** says the content matches the fingerprint recorded inside it. Anybody who edits the
+//   bundle can recompute the fingerprint, so on its own it proves only that nothing was corrupted
+//   in transit - not that nobody changed it on purpose. It is still worth having: it gives a bundle
+//   a stable identity that a release note or a ticket can quote.
+//
+//   A **signature** says the holder of a private key produced this exact content. That is the claim
+//   people mean by "signed", and it is only available when a key exists.
+//
+// A tool that prints "signed" over a bare hash is doing the thing this whole project exists not to
+// do, so the words are kept apart everywhere: in the type, in the report, and in the verifier.
+import { createHash, createPrivateKey, createPublicKey, sign as cryptoSign, verify as cryptoVerify } from 'node:crypto';
+/**
+ * The bundle's content, in a form that hashes the same everywhere: keys in order, the seal itself
+ * left out, and the time it was produced kept in, because a bundle for a different moment is a
+ * different bundle.
+ */
+export function canonical(bundle) {
+    const ordered = (value) => {
+        if (Array.isArray(value))
+            return value.map(ordered);
+        if (value && typeof value === 'object') {
+            return Object.fromEntries(Object.entries(value)
+                .filter(([k]) => k !== 'seal')
+                .sort(([a], [b]) => a.localeCompare(b))
+                .map(([k, v]) => [k, ordered(v)]));
+        }
+        return value;
+    };
+    return JSON.stringify(ordered(bundle));
+}
+export const digestOf = (bundle) => createHash('sha256').update(canonical(bundle)).digest('hex');
+/**
+ * Seals a bundle: always a digest, and a signature when a key is given. The key is a PEM Ed25519
+ * private key, from `TEWIP_ATTEST_KEY` (a path or the PEM itself). Nothing is generated silently:
+ * without a key there is no signature and the bundle says so rather than implying one.
+ */
+export function seal(bundle, privateKeyPem) {
+    const digest = digestOf(bundle);
+    if (!privateKeyPem?.trim())
+        return { digest };
+    try {
+        const key = createPrivateKey(privateKeyPem);
+        if (key.asymmetricKeyType !== 'ed25519')
+            throw new Error(`the signing key is ${key.asymmetricKeyType}, and Tewip signs with ed25519`);
+        return { digest, signature: cryptoSign(null, Buffer.from(digest, 'hex'), key).toString('base64'), algorithm: 'ed25519' };
+    }
+    catch (error) {
+        // A key that does not work is not a reason to ship an unmarked bundle quietly.
+        throw new Error(`the attestation could not be signed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/** Checks a sealed bundle, and says exactly what that check does and does not establish. */
+export function check(bundle, publicKeyPem) {
+    const recorded = bundle.seal?.digest ?? '';
+    const contentMatches = Boolean(recorded) && recorded === digestOf(bundle);
+    if (!recorded) {
+        return { contentMatches: false, signature: 'absent', says: 'this bundle carries no digest at all, so nothing about it can be checked' };
+    }
+    if (!contentMatches) {
+        return { contentMatches: false, signature: bundle.seal?.signature ? 'invalid' : 'absent', says: 'the content does not match the digest recorded inside it: it has been changed since it was written' };
+    }
+    if (!bundle.seal?.signature) {
+        return {
+            contentMatches: true,
+            signature: 'absent',
+            says: 'the content matches its own digest, and nothing more: no signature was made, so this shows the bundle is undamaged, not that nobody edited it - an editor can recompute a digest',
+        };
+    }
+    if (!publicKeyPem?.trim()) {
+        return { contentMatches: true, signature: 'no-key-given', says: 'the content matches its own digest and carries a signature, but no public key was given, so the signature was not checked' };
+    }
+    try {
+        const ok = cryptoVerify(null, Buffer.from(recorded, 'hex'), createPublicKey(publicKeyPem), Buffer.from(bundle.seal.signature, 'base64'));
+        return {
+            contentMatches: true,
+            signature: ok ? 'valid' : 'invalid',
+            says: ok
+                ? 'the content matches its digest and the signature is the holder of that key over this exact content'
+                : 'the content matches its digest, but the signature does not belong to this key and this content',
+        };
+    }
+    catch (error) {
+        return { contentMatches: true, signature: 'invalid', says: `the signature could not be checked: ${error instanceof Error ? error.message : String(error)}` };
+    }
+}

package/dist/engine/pursue/act.js

@@ -0,0 +1,39 @@
+/**
+ * What Tewip may carry out, and with what. Anything absent is refused: reporting a real bug, for
+ * instance, is deliberately not an action - it is for a person to read.
+ */
+export function planFor(decision) {
+    switch (decision.act) {
+        case 'cover-gap': {
+            // `write` drafts the test, runs it, breaks it on purpose to see it fail, and keeps it only
+            // if both hold. The scenario id is in the decision's own next step.
+            const id = /write a test for ([\w-]+)/.exec(decision.next)?.[1];
+            return id ? { command: ['write', '--only', id], target: `scenario ${id}` } : null;
+        }
+        case 'attest':
+            return { command: ['attest'], target: 'the evidence bundle' };
+        default:
+            return null;
+    }
+}
+/** Why an action was not carried out, in words a person can act on. */
+export const cannotAct = {
+    'look-first': 'there is nothing to act on until a report has been read',
+    'triage-real-bug': 'a real bug is for a person to see, and Tewip will not work around one on its own',
+    'rerun-environment': 'a re-run belongs to whatever runs the tests, not to Tewip',
+    'settle-flaky': 'settling a flaky test changes a test file, which Tewip does only when asked directly with `tewip fix`',
+    'triage-undecided': 'Tewip cannot say why these failed, so it has nothing it could safely do about them',
+    'cover-gap': '',
+    attest: '',
+    'stand-down': 'there is nothing here that matches the goal',
+};
+/**
+ * Has this exact action already been tried against this exact evidence? A scheduled run that keeps
+ * attempting an impossible task is the failure mode that makes people turn an agent off. A new run
+ * is new evidence and unblocks it; running again over the same report does not.
+ *
+ * Refusals are not counted: refusing costs nothing and says nothing about whether it would work.
+ */
+export function alreadyTried(records, act, target, runId) {
+    return records.find((r) => r.act === act && r.target === target && r.runId === runId && r.outcome !== 'refused') ?? null;
+}

package/dist/engine/pursue/pursue-command.js

@@ -4,9 +4,11 @@
 // it chose, and only through the gates that already prove a change before keeping it. There is no
 // mode in which it loops unattended: an agent that keeps going until it decides to stop is the
 // thing teams roll back, and nothing here needs it.
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { datasetFiles, readJsonl, readTriageRecords } from '../../reporters/store.js';
+import { alreadyTried, cannotAct, planFor } from './act.js';
 import { decide } from './policy.js';
 const words = (text) => (text.toLowerCase().match(/[a-z][a-z0-9]{2,}/g) ?? []).filter((w) => !['the', 'and', 'for', 'this', 'that', 'with', 'keep', 'green', 'sprint', 'flow', 'test', 'tests'].includes(w));
 /** Does this test or scenario belong to the goal? Deterministic, so a person can predict it. */
@@ -53,6 +55,7 @@ export function observe(root, goal, only) {
         uncovered: uncoveredScenarios(root, wanted, attempted),
         passing: attempted.length - failing.length,
         noHistory: runs.length === 0,
+        runId: newest?.runId ?? '',
     };
 }
 /** Scenarios of a kept plan that no attempted test can be matched to, worst priority first. */
@@ -108,15 +111,100 @@ export function renderPursuit(goal, seen, decision, acting) {
         : 'Tewip has not done anything: this is a decision, and the action is yours.', '', 'The order of these decisions is fixed and written down, not chosen by a model: a real bug first,', 'then the environment, then flakiness, then a coverage gap, and only then is a goal worth attesting.');
     return lines.join('\n');
 }
+/** The audit file the team owns: every action Tewip took on its own, and every one it refused. */
+const auditPath = (root) => join(root, '.tewip', 'actions.jsonl');
+export function actionsTaken(root) {
+    try {
+        return readFileSync(auditPath(root), 'utf8')
+            .split(String.fromCharCode(10))
+            .filter(Boolean)
+            .map((l) => JSON.parse(l));
+    }
+    catch {
+        return [];
+    }
+}
+function record(root, entry) {
+    mkdirSync(dirname(auditPath(root)), { recursive: true });
+    appendFileSync(auditPath(root), JSON.stringify(entry) + String.fromCharCode(10), 'utf8');
+}
+/**
+ * The Tewip command line belonging to *this* build, found from this file rather than from how the
+ * process was started.
+ *
+ * This is not a detail. The first version used process.argv[1], which is the command line only when
+ * a person typed it: under a test runner argv[1] is the test file, so acting re-ran the test file,
+ * which acted again, which re-ran it - a fork bomb that froze the machine it was written on. What
+ * re-enters Tewip has to be Tewip, established here, or nothing is carried out at all.
+ */
+export function cliEntry() {
+    const here = import.meta.dirname;
+    for (const candidate of [join(here, '..', '..', 'cli', 'tewip.ts'), join(here, '..', '..', 'cli', 'tewip.js')]) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * Carries out the one action that was decided, by running the command that already proves it.
+ * Tewip does not do the work here; it asks the gate to.
+ */
+function carryOut(cmd, decision, observed) {
+    const plan = planFor(decision);
+    const runId = observed.runId ?? '';
+    const note = (outcome, detail, target = plan?.target ?? '') => ({
+        at: new Date().toISOString(),
+        goal: cmd.goal,
+        act: decision.act,
+        target,
+        command: plan ? 'tewip ' + plan.command.join(' ') : '',
+        runId,
+        outcome,
+        detail,
+    });
+    if (!plan) {
+        const why = cannotAct[decision.act] || 'this is not something Tewip carries out on its own';
+        record(cmd.root, note('refused', why, decision.act));
+        return 'Not carried out: ' + why + '.';
+    }
+    const tried = alreadyTried(actionsTaken(cmd.root), decision.act, plan.target, runId);
+    if (tried) {
+        record(cmd.root, note('refused', 'already attempted at ' + tried.at + ', on the same evidence'));
+        return ['Not carried out: Tewip already attempted this at ' + tried.at.slice(0, 19).replace('T', ' ') + ' UTC, and nothing has happened since that would make the outcome different.', '', 'That attempt ' + (tried.outcome === 'done' ? 'succeeded' : 'did not finish') + ': ' + tried.detail, '', 'Run ' + tried.command + ' yourself if you want it tried again.'].join(String.fromCharCode(10));
+    }
+    // Re-enter this same build, so an installed Tewip runs the installed gates and a checkout runs
+    // the checkout's - never a different version from the one that decided, and never whatever
+    // happens to have started this process.
+    const entry = cliEntry();
+    if (!entry) {
+        record(cmd.root, note('refused', 'the Tewip command line could not be found next to this build, so there is nothing safe to re-enter'));
+        return 'Not carried out: Tewip could not find its own command line beside this build, and it will not guess at one. Run ' + 'tewip ' + plan.command.join(' ') + ' yourself.';
+    }
+    const ran = spawnSync(process.execPath, [entry, ...plan.command], { cwd: cmd.root, encoding: 'utf8', timeout: 20 * 60_000, maxBuffer: 32 * 1024 * 1024 });
+    const output = ((ran.stdout ?? '') + (ran.stderr ?? '')).trim();
+    const ok = ran.status === 0;
+    // What the audit file remembers: the headline of a success, the tail of a failure. A failure's
+    // reason is at the end of what it printed; a success's is at the start.
+    const lines = output.split(String.fromCharCode(10)).map((l) => l.trim()).filter(Boolean);
+    const detail = (ok ? lines[0] ?? 'it printed nothing' : lines.slice(-3).join(' ')).slice(0, 300);
+    record(cmd.root, note(ok ? 'done' : 'failed', detail));
+    return [
+        ok ? 'Carried out: tewip ' + plan.command.join(' ') : 'Tried and did not finish: tewip ' + plan.command.join(' '),
+        '',
+        output.slice(-2000),
+        '',
+        ok
+            ? 'Anything kept by that command was proved by it; anything unproved was thrown away. Written to .tewip/actions.jsonl.'
+            : 'Nothing was kept. Written to .tewip/actions.jsonl.',
+    ].join(String.fromCharCode(10));
+}
 export function runPursue(cmd) {
     const observed = observe(cmd.root, cmd.goal, cmd.name);
     const decision = decide(cmd.goal, observed);
     const report = renderPursuit(cmd.goal, observed, decision, Boolean(cmd.act));
     console.log(report);
-    if (cmd.act && decision.changesFiles) {
-        console.error('\n`--act` is accepted, but Tewip carries out a change only through the command that proves it.');
-        console.error(`Run: ${decision.next}`);
-    }
+    if (cmd.act)
+        console.log(String.fromCharCode(10) + '---' + String.fromCharCode(10) + carryOut(cmd, decision, observed));
     if (cmd.out) {
         mkdirSync(dirname(resolve(cmd.out)), { recursive: true });
         writeFileSync(resolve(cmd.out), `${report}\n`, 'utf8');

package/dist/engine/recall/recall-command.js

@@ -20,17 +20,24 @@ function kept(root, only) {
     }
     return { records, corrections };
 }
-export function runRecall(cmd) {
+/**
+ * The report, without printing it. An MCP server speaks JSON-RPC over stdout, so anything one of
+ * its tools calls has to return its answer: a stray console.log corrupts every response the
+ * assistant receives, and the corruption looks like the tool being broken rather than noisy.
+ */
+export function recallReport(cmd) {
     const { records, corrections } = kept(cmd.root, cmd.name);
     if (records.length === 0) {
-        const empty = 'Nothing has been kept here yet, so there is no history to search. Run `tewip explain <report>` first.';
-        console.log(empty);
-        return empty;
+        return { report: 'Nothing has been kept here yet, so there is no history to search. Run `tewip explain <report>` first.', searched: 0, corrections: 0 };
     }
     const found = recall(cmd.question, memories(records, corrections), { testId: cmd.testId, limit: cmd.limit ?? 5 });
-    const report = renderRecall(cmd.question, found);
+    return { report: renderRecall(cmd.question, found), searched: records.length, corrections: corrections.length };
+}
+export function runRecall(cmd) {
+    const { report, searched, corrections } = recallReport(cmd);
     console.log(report);
-    console.error(`\nSearched ${records.length} kept failure(s) and ${corrections.length} correction(s). No model was called.`);
+    if (searched > 0)
+        console.error(`\nSearched ${searched} kept failure(s) and ${corrections} correction(s). No model was called.`);
     if (cmd.out) {
         mkdirSync(dirname(resolve(cmd.out)), { recursive: true });
         writeFileSync(resolve(cmd.out), `${report}\n`, 'utf8');

package/dist/engine/trace/trace-command.js

@@ -46,15 +46,18 @@ function history(root, only) {
     runs.sort((a, b) => (a.finishedAt > b.finishedAt ? 1 : -1));
     return { runs, records };
 }
-export function runTrace(cmd) {
+/** The thread and its report, without printing: an MCP tool must return, never write to stdout. */
+export function traceReport(cmd) {
     const found = plans(cmd.root, cmd.only);
     const { runs, records } = history(cmd.root, cmd.name);
     const traced = found.map((plan) => tracePlan(plan, runs, records));
-    const report = renderTrace(traced);
+    return { traced, report: renderTrace(traced), plans: found.length, runs: runs.length };
+}
+export function runTrace(cmd) {
+    const { traced, report, plans: found, runs } = traceReport(cmd);
     console.log(report);
-    if (found.length > 0) {
-        console.error(`\nTraced ${found.length} plan(s) against ${runs.length} kept run(s). No model was called.`);
-    }
+    if (found > 0)
+        console.error(`\nTraced ${found} plan(s) against ${runs} kept run(s). No model was called.`);
     if (cmd.out) {
         mkdirSync(dirname(resolve(cmd.out)), { recursive: true });
         writeFileSync(resolve(cmd.out), `${report}\n`, 'utf8');

package/dist/mcp/server.js

@@ -12,7 +12,7 @@ import { isAbsolute } from 'node:path';
 import { z } from 'zod';
 import { githubCiReport } from './github-report.js';
 import { explainFailure, listDatasets, listFailedRuns, runView, windowView } from './tools.js';
-const server = new McpServer({ name: 'tewip', version: '0.4.0' });
+const server = new McpServer({ name: 'tewip', version: '0.5.0' });
 const readOnly = { readOnlyHint: true, destructiveHint: false, idempotentHint: true };
 const dataset = z.string().optional().describe('Dataset directory relative to the Tewip repo, e.g. "data/real/gutenberg-holdout". Default: data/ (what the reporter collected). See list_datasets.');
 const run = z.string().optional().describe('Run id or a unique part of it. Default: the latest run with failures.');
@@ -77,4 +77,50 @@ server.registerTool('test_plan', {
     const { markdown, out } = await planProject({ feature, root: project, diffRange: diff, urls: urls ?? [] });
     return `${markdown}\n\n(Saved to ${out}. To turn it into verified tests, run \`tewip write\` in that folder.)`;
 }));
+/**
+ * The project's own memory, its thread from requirement to run, and its evidence bundle. All three
+ * read what Tewip already kept for a project on this machine, call no model, and change nothing -
+ * which is what makes them safe to hand an assistant that may call them on its own.
+ */
+const project = z.string().describe('Absolute path of the project folder');
+server.registerTool('recall', {
+    title: 'Has this happened here before?',
+    description: "What this project already concluded about a failure like this one: earlier failures that resemble it, what was decided, by which rule or which person, and the run each came from. Answers from records Tewip kept, never from a guess - and says plainly when nothing resembles it. Use before deciding what a failure means, and for questions like \"have we seen this error before?\".",
+    inputSchema: {
+        question: z.string().describe('An error message, or a question in plain words'),
+        project,
+        test: z.string().optional().describe('Narrow to one test id, when the question is about a particular test'),
+    },
+    annotations: readOnly,
+}, ({ question, project: root, test }) => answer(async () => {
+    if (!isAbsolute(root) || !existsSync(root))
+        throw new Error(`project must be an existing absolute path, got "${root}"`);
+    const { recallReport } = await import('../engine/recall/recall-command.js');
+    return recallReport({ root, question, testId: test }).report;
+}));
+server.registerTool('trace_requirements', {
+    title: 'Is this requirement covered, and is it passing?',
+    description: 'Joins the plans Tewip wrote for a project to the tests that cover them and the runs that attempted them. A scenario counts as covered only when a real test can be named, and as passing only when a real run attempted it; everything else is reported as never run or not covered. Use for "are we ready to release?" and "what is not tested?".',
+    inputSchema: { project, only: z.string().optional().describe('Only plans whose title, ticket or feature contains this') },
+    annotations: readOnly,
+}, ({ project: root, only }) => answer(async () => {
+    if (!isAbsolute(root) || !existsSync(root))
+        throw new Error(`project must be an existing absolute path, got "${root}"`);
+    const { traceReport } = await import('../engine/trace/trace-command.js');
+    return traceReport({ root, only }).report;
+}));
+server.registerTool('next_action', {
+    title: 'What should be done next about a goal?',
+    description: 'Given a goal in plain words - "keep the checkout flow green" - says what Tewip would do next and why, from what it can actually see in the project. The order is fixed and published: a real bug first, then the environment, then flakiness, then anything failing it cannot explain, then a coverage gap. It decides only; it never changes a file.',
+    inputSchema: { goal: z.string().describe('The goal, in plain words'), project },
+    annotations: readOnly,
+}, ({ goal, project: root }) => answer(async () => {
+    if (!isAbsolute(root) || !existsSync(root))
+        throw new Error(`project must be an existing absolute path, got "${root}"`);
+    // observe/decide/render are pure; runPursue prints, which would corrupt the protocol.
+    const { observe, renderPursuit } = await import('../engine/pursue/pursue-command.js');
+    const { decide } = await import('../engine/pursue/policy.js');
+    const observed = observe(root, goal);
+    return renderPursuit(goal, observed, decide(goal, observed), false);
+}));
 await server.connect(new StdioServerTransport());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tewip-ai",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Tewip finds why each failing test failed - real bug, flaky test, environment, test data or changed selector - for any stack, from the command line, CI, or your editor.",
   "keywords": [
     "test-failures",