dsh-vibe-math 2.7.0 → 2.7.2

package/tests/math-computation-shared.test.mjs

@@ -116,7 +116,11 @@ console.log('-- math_computation shared contract --')
   await withHost({ installed: [] }, async (state) => {
     const r = await state.call({ op: 'probe' })
     ok(r.ok === false && r.code === 'MATH_ENGINE_NOT_FOUND', 'no engine -> ENGINE_NOT_FOUND')
-    ok(r.next && r.next.kind === 'user-install' && r.next.command, 'ENGINE_NOT_FOUND carries the per-OS user-install guide')
+    // round-9: the guide is per-OS and always carries the SUGGESTED command; `command` itself is only
+    // populated when that OS's package manager is actually resolvable on this machine.
+    ok(r.next && r.next.kind === 'user-install' && r.next.perOs && r.next.perOs.windows && r.next.perOs.linux, 'ENGINE_NOT_FOUND carries the per-OS user-install guide')
+    ok(r.next.suggestedCommand === r.next.perOs[r.next.platform], 'the guide keeps the suggested per-OS command alongside the executable one')
+    ok(r.next.packageManagerAvailable === false ? r.next.command === '' : typeof r.next.command === 'string', 'command ⇔ package-manager availability (never a command that cannot run)')
   })
   await withHost({ packages: { numpy: 'present', sympy: 'missing' } }, async (state) => {
     const r = await state.call({ op: 'probe', packages: ['numpy', 'sympy'] })
@@ -175,10 +179,15 @@ console.log('-- math_computation shared contract --')
   await withHost({}, async (state) => {
     const r = await state.call({ op: 'run', engine: 'cli', mode: 'code', code: 'echo hi', cli: { command: '/fake/bin/mytool', argv: ['--flag', 'x'] } })
     ok(r.ok === true, 'cli runs with DEFAULT params (default-on)')
-    eq(r.argv, ['/fake/bin/mytool', '--flag', 'x'], 'cli argv is command + user argv verbatim')
+    // round-7 (finding 4): mode:'code' append the archived script so the code actually RUNS (the
+    // caller cannot know the runId up front). The user argv stays verbatim in receipt.cli.argv.
+    eq(r.argv.slice(0, 3), ['/fake/bin/mytool', '--flag', 'x'], 'cli argv starts with command + user argv')
+    ok(/Computation\/.*script\.txt$/.test(String(r.argv[3] || '')), 'mode:code appends the archived script path to the effective argv')
+    ok(r.cliScriptAppended === true, 'the return shell flags cliScriptAppended')
     ok(r.engine === 'cli:/fake/bin/mytool' && r.engineInfo.name === 'cli:/fake/bin/mytool', 'cli is labelled cli:<command> in the shell and engineInfo')
     const rj = JSON.parse(state.file(r.receipt.json))
-    ok(rj.engine.name === 'cli:/fake/bin/mytool' && rj.engine.source === 'cli' && rj.cli && rj.cli.argv.length === 2, 'cli receipt records cli:<command>, source=cli and argv')
+    ok(rj.engine.name === 'cli:/fake/bin/mytool' && rj.engine.source === 'cli' && rj.cli && rj.cli.argv.length === 2, 'cli receipt records cli:<command>, source=cli and the USER argv')
+    ok(rj.cli.scriptAppended === true && rj.argv[rj.argv.length - 1] === r.argv[3], 'the receipt records scriptAppended and the executed argv')
   })
   await withHost({ params: { mathMode: 'typed' } }, async (state) => {
     const r = await state.call({ op: 'run', engine: 'cli', mode: 'code', code: 'x', cli: { command: '/fake/bin/mytool' } })
@@ -498,6 +507,424 @@ console.log('-- math_computation shared contract --')
   }
 }
 
+// ── 18. round-6: substitution honesty (A), manager dispatch (B), scope policy (C), version syntax (D)
+{
+  // 18a (A): the rule is part of the frozen rule block and reaches both language lines.
+  ok(M.MATH_RULE_LINES.join('\n').indexOf(M.MATH_SUBSTITUTION_RULE_LINE) !== -1, 'MATH_RULE_LINES carries the substitution-honesty rule (zh)')
+  ok(M.MATH_RULE_LINES_EN.join('\n').indexOf(M.MATH_SUBSTITUTION_RULE_LINE_EN) !== -1, 'MATH_RULE_LINES_EN carries the substitution-honesty rule (en)')
+  ok(/替代方案若改变精确性/.test(String(M.MATH_TOOL_DESCRIPTION)), 'the tool description states the substitution duty (paraphrase)')
+  {
+    const p = await M.probeMathEngines(makeFakeHost({ installed: ['python3'] }).host)
+    const zh = M.mathAvailabilityLine(p, 'zh', 'typed+shell')
+    const en = M.mathAvailabilityLine(p, 'en', 'typed+shell')
+    ok(zh.indexOf('替代必须声明') !== -1, 'the injected (zh) availability line carries the substitution rule')
+    ok(en.indexOf('Declare substitutions') !== -1, 'the injected (en) availability line carries the substitution rule')
+  }
+
+  // 18b (B): python dispatch follows the DETECTED environment, never a guess.
+  {
+    const condaHost = makeFakeHost({ resolveMap: { python3: 'C:/miniconda3/envs/math/python.exe', conda: 'C:/miniconda3/Scripts/conda.exe' } })
+    M.registerMathComputation(condaHost.host)
+    const c = await condaHost.call({ op: 'install', engine: 'python', packages: ['numpy'] })
+    ok(c.ok === true && c.plan.manager === 'conda' && c.plan.managerAssumed === false, 'a conda-style interpreter plans with conda (not guessed)')
+    eq(c.plan.commands[0].argv, ['conda', 'install', '-y', '-c', 'conda-forge', 'numpy'], 'conda install comes from conda-forge')
+    ok(/conda/.test(String(c.message)), 'the plan message names the manager')
+
+    const uvHost = makeFakeHost({ resolveMap: { python3: '/venv/bin/python3', uv: '/venv/bin/uv' } })
+    M.registerMathComputation(uvHost.host)
+    const u = await uvHost.call({ op: 'install', engine: 'python', packages: ['numpy'] })
+    ok(u.ok === true && u.plan.manager === 'uv', 'a uv next to the interpreter plans with uv')
+    eq(u.plan.commands[0].argv, ['uv', 'pip', 'install', 'numpy'], 'uv install uses `uv pip install`')
+
+    const pipHost = makeFakeHost({ resolveMap: { python3: '/usr/bin/python3' } })
+    M.registerMathComputation(pipHost.host)
+    const d = await pipHost.call({ op: 'install', engine: 'python', packages: ['numpy'] })
+    ok(d.ok === true && d.plan.manager === 'pip' && d.plan.managerAssumed === true, 'no marker -> pip fallback, flagged as an ASSUMPTION')
+    eq(d.plan.commands[0].argv, ['/usr/bin/python3', '-m', 'pip', 'install', '--user', 'numpy'], 'the pip fallback keeps the user-scope form')
+    ok(/假设|assum/i.test(String(d.message)), 'the message says the manager is an assumption')
+  }
+
+  // 18c (C): R/Octave/Julia refuse system scope WITH a per-engine reason; conda too.
+  {
+    const h = makeFakeHost({ resolveMap: { Rscript: '/usr/bin/Rscript', octave: '/usr/bin/octave', julia: '/usr/bin/julia' } })
+    M.registerMathComputation(h.host)
+    for (const [engine, marker] of [['r', 'R_LIBS_USER'], ['octave', 'share/packages'], ['julia', 'JULIA_DEPOT_PATH']]) {
+      const r = await h.call({ op: 'install', engine: engine, packages: ['x'], scope: 'system' })
+      ok(r.ok === false && r.code === 'MATH_REFUSED' && r.next && r.next.reason === 'system-scope-unsupported', engine + ': system scope -> MATH_REFUSED(system-scope-unsupported)')
+      ok(String(r.message).indexOf(marker) !== -1, engine + ': the refusal states WHY (mentions ' + marker + ')')
+    }
+    const condaHost = makeFakeHost({ resolveMap: { python3: 'C:/miniconda3/envs/math/python.exe', conda: 'C:/miniconda3/Scripts/conda.exe' } })
+    M.registerMathComputation(condaHost.host)
+    const cs = await condaHost.call({ op: 'install', engine: 'python', packages: ['numpy'], scope: 'system' })
+    ok(cs.ok === false && cs.next.reason === 'system-scope-unsupported' && /conda/.test(String(cs.message)), 'conda has no system scope and says so')
+  }
+
+  // 18d (D): version syntax is passed through where the manager understands it, refused otherwise.
+  {
+    ok(M.validateMathArgs({ op: 'run', mode: 'code', code: 'x', packages: ['numpy==1.2'] }, {}).ok === true, 'pkg==1.2 is accepted (pass-through)')
+    ok(M.validateMathArgs({ op: 'run', mode: 'code', code: 'x', packages: ['numpy=1.2'] }, {}).ok === true, 'pkg=1.2 (conda form) is accepted')
+    ok(M.validateMathArgs({ op: 'run', mode: 'code', code: 'x', packages: ['numpy[extra]>=1.2'] }, {}).ok === true, 'extras + comparator are accepted')
+    const badSpec = M.validateMathArgs({ op: 'run', mode: 'code', code: 'x', packages: ['numpy; rm -rf /'] }, {})
+    ok(badSpec.ok === false && badSpec.code === 'MATH_INVALID_ARGUMENT' && badSpec.next && badSpec.next.reason === 'unsupported-version-syntax', 'a shell-ish spec is refused with unsupported-version-syntax')
+
+    const ph = makeFakeHost({ packages: { sympy: 'present' } })
+    M.registerMathComputation(ph.host)
+    await ph.call({ op: 'run', engine: 'python', mode: 'code', code: 'print(1)\n', packages: ['sympy==1.12'] })
+    const pkgSpawns = ph.spawns.filter((s) => s.argv.join(' ').indexOf('sympy') !== -1)
+    ok(pkgSpawns.length > 0 && pkgSpawns.every((s) => s.argv.join(' ').indexOf('sympy==1.12') === -1), 'presence is probed by BASE NAME (the constraint never reaches the probe)')
+    const plan = await ph.call({ op: 'install', engine: 'python', packages: ['sympy==1.12'] })
+    ok(plan.ok === true && plan.plan.commands[0].argv[plan.plan.commands[0].argv.length - 1] === 'sympy==1.12', 'the install plan passes the spec through verbatim')
+    ok(!!plan.plan.versionPolicy, 'the plan states the version policy (solving belongs to the manager)')
+  }
+}
+
+// ── 19. round-7: probe reports the REQUESTED engine (fix 1) + DSH bundled-runtime discovery (fix 2)
+{
+  // 19a (fix 1): `probe {engine:'r'}` must describe r - not the first allowed engine (python).
+  {
+    const hr = makeFakeHost({ installed: ['python3', 'python', 'Rscript'] })
+    M.registerMathComputation(hr.host)
+    const p = await hr.call({ op: 'probe', engine: 'r' })
+    ok(p.ok === true && p.engine === 'r', 'probe with engine:r reports engine:r (not python)')
+    ok(!!p.engineInfo && p.engineInfo.name === 'r' && !!p.engineInfo.version, "probe reports the requested engine's version/path")
+    ok(!p.next, 'a usable requested engine yields no install guidance')
+    const pp = await hr.call({ op: 'probe', engine: 'python' })
+    ok(pp.ok === true && pp.engine === 'python' && pp.engineInfo.name === 'python', 'probe with engine:python reports python (each request is honoured)')
+  }
+  // 19b (fix 1): a MISSING requested engine must not blame python in the guidance.
+  {
+    const hm = makeFakeHost({ installed: ['python3', 'python'] })
+    M.registerMathComputation(hm.host)
+    const p = await hm.call({ op: 'probe', engine: 'r' })
+    ok(p.ok === false && p.code === 'MATH_ENGINE_NOT_FOUND' && p.engine === 'r', 'a missing requested engine is reported as THAT engine (r, not python)')
+    ok(p.next && p.next.kind === 'user-install' && p.next.engine === 'r' && !!p.next.perOs, 'the install guidance is for the REQUESTED engine (r), with per-OS commands')
+    const msg = String(p.message)
+    ok(/试过：r|请求：r/.test(msg) && !/python/i.test(msg), 'the message names the requested engine (r), never a python fallback')
+  }
+  // 19c (fix 2): a DSH-bundled runtime is discovered as a LAST resort and used like any engine.
+  {
+    const absTree = {
+      'X:/home/.dsh/dsh-runtimes': [{ name: 'dsh-primary-runtime', type: 'directory' }, { name: 'dsh-other-runtime', type: 'directory' }],
+      'X:/home/.dsh/dsh-runtimes/dsh-primary-runtime/dependencies/python': [{ name: 'python.exe', type: 'file' }, { name: 'python3.exe', type: 'file' }],
+      'X:/home/.dsh/dsh-runtimes/dsh-other-runtime/dependencies/python': [],
+    }
+    const hb = makeFakeHost({ installed: [], runtimeRoots: ['X:/home/.dsh'], absTree: absTree })
+    M.registerMathComputation(hb.host)
+    const p = await hb.call({ op: 'probe', engine: 'python' })
+    ok(p.ok === true && p.engine === 'python' && p.engineInfo.name === 'python', 'a bundled DSH runtime is found when PATH has nothing')
+    ok(/dsh-runtimes\/dsh-primary-runtime\/dependencies\/python\/python/.test(p.engineInfo.path), 'the discovered path comes from the generically globbed runtime tree')
+    const r = await hb.call({ op: 'run', engine: 'python', mode: 'code', code: 'print(1)\n' })
+    ok(r.ok === true && !!r.engineInfo.version, 'a run on the bundled runtime succeeds and reports its version')
+    ok(!r.next, 'a found bundled runtime emits NO install guidance')
+    // The bundled runtime must not be invented when the tree is absent.
+    const hn = makeFakeHost({ installed: [] })
+    M.registerMathComputation(hn.host)
+    const n = await hn.call({ op: 'probe', engine: 'python' })
+    ok(n.ok === false && n.code === 'MATH_ENGINE_NOT_FOUND' && n.next && n.next.kind === 'user-install', 'with no PATH engine and no runtime tree the per-OS guidance still fires')
+  }
+  // 19d (finding 3): the cli package precheck runs against the FAMILY of `cli.command`, not the
+  // generic cli descriptor (which has no packageProbe and therefore reported a false "missing").
+  {
+    const hc = makeFakeHost({ installed: [], packages: { numpy: 'present' } })
+    M.registerMathComputation(hc.host)
+    const r = await hc.call({ op: 'run', engine: 'cli', mode: 'code', code: 'print(1)\n', cli: { command: '/fake/bin/python3' }, packages: ['numpy'] })
+    ok(r.ok === true, 'cli + packages: a python-family command prechecks with the python probe (numpy present => the run proceeds)')
+    const probes = hc.spawns.filter((s) => s.argv.join(' ').indexOf('numpy') !== -1)
+    ok(probes.length > 0 && probes.every((s) => String(s.argv[0]).indexOf('python3') !== -1), 'the package precheck ran against cli.command itself')
+    // An unrecognisable command must SKIP the precheck (never a false missing) and say so.
+    const hu = makeFakeHost({ installed: [] })
+    M.registerMathComputation(hu.host)
+    const ru = await hu.call({ op: 'run', engine: 'cli', mode: 'code', code: 'print(1)\n', cli: { command: '/fake/bin/mytool' }, packages: ['numpy'] })
+    ok(ru.ok === true && (ru.warnings || []).some((w) => w.code === 'PACKAGE_PRECHECK_SKIPPED'), 'an unknown cli family skips the precheck with an explicit warning (no false missing-packages)')
+  }
+  // 19e (finding 5): cli reports the REAL version of the resolved command when its family is known.
+  {
+    const hv = makeFakeHost({ installed: [] })
+    M.registerMathComputation(hv.host)
+    const p = await hv.call({ op: 'probe', engine: 'cli', cli: { command: '/fake/bin/python3' } })
+    ok(p.ok === true && p.engineInfo && p.engineInfo.version === '1.2.3', 'probe(engine:cli) reports the real version of the resolved command')
+    const r = await hv.call({ op: 'run', engine: 'cli', mode: 'code', code: 'print(1)\n', cli: { command: '/fake/bin/python3' } })
+    ok(r.engineInfo.version === '1.2.3', 'run(engine:cli) reports the real command version (not "unknown")')
+  }
+  // 19f (finding 6, found on the real bundled python): the probe code iterates `sys.argv[1:]`, so the
+  // names must arrive as SEPARATE argv items - a comma-joined single item makes python look up one
+  // package literally named "numpy,pandas" and report everything missing.
+  {
+    const hp = makeFakeHost({ installed: ['python3'], packages: { numpy: 'present', pandas: 'present' } })
+    M.registerMathComputation(hp.host)
+    await hp.call({ op: 'run', engine: 'python', mode: 'code', code: 'print(1)\n', packages: ['numpy', 'pandas'] })
+    const probe = hp.spawns.find((s) => s.argv.join(' ').indexOf('numpy') !== -1)
+    ok(!!probe && probe.argv.indexOf('numpy') !== -1 && probe.argv.indexOf('pandas') !== -1, 'the python package probe passes ONE argv item per package (sys.argv-based probe)')
+    ok(!!probe && probe.argv.join(' ').indexOf('numpy,pandas') === -1, 'the probe never passes the comma-joined list as a single argv item')
+    // round-7 (live): a real host rejected probe argv containing shell metacharacters (| %), so no
+    // probe argv may carry them - the parsers accept both `name:state` and `name state` shapes.
+    ok(!!probe && !/[|%]/.test(probe.argv.join(' ')), 'no probe argv contains a shell metacharacter (| or %)')
+    for (const name of ['python', 'r', 'octave', 'julia']) {
+      const d = (await import('../vibe-math-v2/math-engines.js')).MATH_ENGINES[name]
+      for (const a of (d.packageProbe.argv || [])) ok(!/[|%]/.test(String(a)), name + ' probe template has no | or %: ' + String(a).slice(0, 40))
+      ok(!/[|%]/.test(String(d.probeCode || 'numpy ok line')), name + ' probeCode has no | or %')
+    }
+  }
+  // 19f-bis: cli + mode:'code' actually PASSES the script (finding 4) - verified through argv shape.
+  {
+    const hs = makeFakeHost({ installed: [] })
+    M.registerMathComputation(hs.host)
+    const r = await hs.call({ op: 'run', engine: 'cli', mode: 'code', code: 'print(1)\n', cli: { command: '/fake/bin/python3' } })
+    const last = String(r.argv[r.argv.length - 1] || '')
+    ok(r.ok === true && /script\.txt$/.test(last), 'cli + code: the archived script is last in argv (it is really executed, not a REPL)')
+    const runSpawn = hs.spawns.filter((s) => String(s.argv[s.argv.length - 1] || '').indexOf('script.txt') !== -1)
+    ok(runSpawn.length === 1, 'the executed argv carried the script path to the process')
+    // …but when the CALLER's argv already runs code (-c/-m/-e/--eval), the caller's argv wins: the
+    // archived script must NOT be appended after it (python would read it as sys.argv[1]).
+    const rc = await hs.call({ op: 'run', engine: 'cli', mode: 'code', code: 'print(1)\n', cli: { command: '/fake/bin/python3', argv: ['-c', 'print(1)'] } })
+    ok(rc.ok === true && rc.cliScriptAppended === false, 'cli + code with a caller program slot (-c) does NOT append the archived script')
+    ok(rc.argv.join(' ').indexOf('script.txt') === -1, 'the executed argv is exactly the caller argv (no script path)')
+    ok(!!rc.receipt && !!rc.receipt.json, 'the skipped-append run still writes a receipt')
+  }
+  // 19g (live-session fix): an engine that RESOLVED but whose version probe failed must NOT come with
+  // install guidance (the user does not need to install anything) and must carry the diagnostic.
+  {
+    const hh = makeFakeHost({ installed: ['python3', 'python'], versionProbeFails: true })
+    M.registerMathComputation(hh.host)
+    const p = await hh.call({ op: 'probe', engine: 'python' })
+    ok(p.ok === false && p.code === 'MATH_ENGINE_UNUSABLE', 'a resolved engine whose probe fails => MATH_ENGINE_UNUSABLE')
+    ok(!p.next || p.next.kind !== 'user-install', 'unusable (but FOUND) engine carries NO install guidance')
+    ok(!!p.probe && Array.isArray(p.probe.argv) && p.probe.argv[0].indexOf('python3') !== -1, 'the failure carries the probe diagnostic (argv)')
+    ok(!!p.probe && p.probe.exit === 1 && p.probe.stderrTail === 'probe boom', 'the diagnostic carries exit + stderr tail')
+    ok(/MATH_ENGINE_UNUSABLE/.test(p.code) && /exit=1/.test(String(p.message)), 'the message states the probe exit code (never an opaque "unusable")')
+    // A deterministic failure is NOT retried (no retryDiag, no retry storm), only a cold/null/timeout
+    // signature is - see 19h.
+    ok(!(p.probe && p.probe.retried), 'a deterministic probe failure is NOT retried (no retryDiag)')
+  }
+  // 19h (live-session fix): the real host intermittently returns a NULL spawn early in a session.
+  // The retry must cover spawned:false / exit:null (not just timeouts) so the probe still succeeds.
+  {
+    const hN = makeFakeHost({ installed: ['python3', 'python'], nullSpawnTimes: 2 })
+    M.registerMathComputation(hN.host)
+    const p = await hN.call({ op: 'probe', engine: 'python' })
+    ok(p.ok === true && p.engine === 'python' && p.engineInfo.version === '1.2.3', 'a transient NULL spawn is retried and the probe still succeeds')
+    ok(hN.spawns.filter((s) => s.nullSpawn).length === 2, 'the null spawns are visible in the seam (2 consumed)')
+  }
+  // 19i (live-session fix): a package precheck that could not RUN must never be reported as
+  // "missing package", and the skip must be explicit (fail-open + named warning).
+  {
+    const hP = makeFakeHost({ installed: ['python3'], packageProbeNullTimes: 9 })
+    M.registerMathComputation(hP.host)
+    const r = await hP.call({ op: 'run', engine: 'python', mode: 'code', code: 'print(1)\n', packages: ['numpy'] })
+    ok(r.ok !== false || r.code !== 'MATH_MISSING_PACKAGES', 'a precheck that could not run is NEVER reported as a missing package')
+    ok((r.warnings || []).some((w) => w.code === 'PACKAGE_PRECHECK_UNKNOWN'), 'the un-runnable precheck is reported explicitly (PACKAGE_PRECHECK_UNKNOWN)')
+  }
+}
+
+// ── 20. round-7 cross-cutting invariant: EVERY response must be JSON-serialisable
+// (a real session got `Converting circular structure to JSON ... property 'retryDiag' closes the
+// circle` from a probe/run response, which meant the caller saw no result at all). This applies to
+// all four presets because they all ship this module.
+{
+  const cases = []
+  const push = (label, r) => cases.push({ label, r })
+  {
+    const h = makeFakeHost({ installed: ['python3', 'python', 'Rscript'], packages: { numpy: 'present' } })
+    M.registerMathComputation(h.host)
+    push('probe ok', await h.call({ op: 'probe', engine: 'python' }))
+    push('probe missing engine', await h.call({ op: 'probe', engine: 'octave' }))
+    push('run ok', await h.call({ op: 'run', engine: 'python', mode: 'code', code: 'print(1)\n' }))
+    push('run bad mode', await h.call({ op: 'run', engine: 'python', mode: 'nope' }))
+    push('run missing pkg', await h.call({ op: 'run', engine: 'python', mode: 'code', code: 'x\n', packages: ['pandas'] }))
+    push('receipt missing', await h.call({ op: 'receipt', id: 'nope' }))
+    push('install plan', await h.call({ op: 'install', engine: 'python', packages: ['numpy'] }))
+    push('install commercial', await h.call({ op: 'install', engine: 'matlab', packages: ['MATLAB'] }))
+    push('install system scope r', await h.call({ op: 'install', engine: 'r', packages: ['x'], scope: 'system' }))
+    push('unsupported spec', await h.call({ op: 'run', engine: 'python', mode: 'code', code: 'x\n', packages: ['numpy; rm -rf /'] }))
+    push('unknown engine', await h.call({ op: 'run', engine: 'nope', mode: 'code', code: 'x\n' }))
+  }
+  {
+    const h = makeFakeHost({ installed: ['python3'], versionProbeFails: true })
+    M.registerMathComputation(h.host)
+    push('probe unusable (probe diagnostics)', await h.call({ op: 'probe', engine: 'python' }))
+  }
+  {
+    // A RETRIED probe carries retryDiag: that is exactly where the circular payload came from.
+    const h = makeFakeHost({ installed: ['python3'], nullSpawnTimes: 40 })
+    M.registerMathComputation(h.host)
+    push('probe unusable after retries (retryDiag present)', await h.call({ op: 'probe', engine: 'python' }))
+  }
+  {
+    const h = makeFakeHost({ installed: ['python3'], packageProbeNullTimes: 9 })
+    M.registerMathComputation(h.host)
+    push('run with un-runnable precheck', await h.call({ op: 'run', engine: 'python', mode: 'code', code: 'x\n', packages: ['numpy'] }))
+  }
+  {
+    const h = makeFakeHost({ installed: [] })
+    M.registerMathComputation(h.host)
+    push('probe nothing', await h.call({ op: 'probe', engine: 'python' }))
+  }
+  {
+    const h = makeFakeHost({ resolveThrows: true })
+    M.registerMathComputation(h.host)
+    push('probe resolve throws', await h.call({ op: 'probe', engine: 'python' }))
+  }
+  for (const c of cases) {
+    let json = null
+    let err = null
+    try { json = JSON.stringify(c.r) } catch (e) { err = String((e && e.message) || e) }
+    ok(json !== null, '★ response is JSON-serialisable: ' + c.label + (err ? ' (' + err + ')' : ''))
+  }
+  // The diagnostics themselves must never carry a back-reference.
+  {
+    const h = makeFakeHost({ installed: ['python3'], nullSpawnTimes: 2 })
+    M.registerMathComputation(h.host)
+    const r = await h.call({ op: 'probe', engine: 'python' })
+    ok(r.ok === true, 'the null-spawn retry recovers (JSON invariant context)')
+    const h2 = makeFakeHost({ installed: ['python3'], versionProbeFails: true })
+    M.registerMathComputation(h2.host)
+    const u = await h2.call({ op: 'probe', engine: 'python' })
+    ok(!!u.probe && JSON.stringify(u.probe).indexOf('retryDiag') === -1 ? true : !!u.probe, 'a deterministic failure still exposes its probe diagnostics')
+  }
+}
+
+// ── 21. round-7 (live root cause): probes must not depend on the project root EXISTING
+// The real host answers a spawn whose cwd does not exist with `spawned:true, exit:null` (retries
+// cannot help). On a brand-new session the project root does not exist yet, so the version probe and
+// the package precheck must run from a cwd that is guaranteed to exist.
+{
+  const FRESH = '/fresh/nonexistent/workspace'
+  const h = makeFakeHost({ installed: ['python3', 'python'], projectRoot: FRESH, packages: { numpy: 'present' } })
+  M.registerMathComputation(h.host)
+  const p = await h.call({ op: 'probe', engine: 'python' })
+  ok(p.ok === true && p.engine === 'python' && p.engineInfo.version === '1.2.3', '★ a probe on a FRESH (non-existent) project root still succeeds with a real version')
+  const versionSpawns = h.spawns.filter((s) => /--version/.test(s.argv.join(' ')))
+  ok(versionSpawns.length > 0, 'the version probe actually spawned')
+  ok(versionSpawns.every((s) => String(s.cwd) !== FRESH), '★ no version probe spawn uses the non-existent project root as cwd')
+  ok(versionSpawns.every((s) => !s.nullSpawn), 'no version probe spawn reported exit:null (fresh-root signature)')
+  const r = await h.call({ op: 'run', engine: 'python', mode: 'code', code: 'print(1)\n', packages: ['numpy'] })
+  const pkgSpawns = h.spawns.filter((s) => s.argv.join(' ').indexOf('numpy') !== -1)
+  ok(r.ok === true, 'a run with packages on a FRESH root passes the precheck')
+  ok(pkgSpawns.length > 0 && pkgSpawns.every((s) => String(s.cwd) !== FRESH), '★ the package precheck also avoids the non-existent project root')
+  ok(!(r.warnings || []).some((w) => w.code === 'PACKAGE_PRECHECK_UNKNOWN'), 'the precheck RAN (no PACKAGE_PRECHECK_UNKNOWN on a fresh root)')
+}
+
+// ── 22. round-8 (P0/D3): member-facing artifact paths must be OPENABLE by members
+// The receipt's scriptPath is PROJECT-ROOT relative, but members' file tools resolve against the
+// SESSION CWD. The receipt/return therefore carry the absolute `scriptAbs` and the `cwd` to join with.
+{
+  const h = makeFakeHost({ installed: ['python3'] })
+  M.registerMathComputation(h.host)
+  const r = await h.call({ op: 'run', engine: 'python', mode: 'code', code: 'print(1)\n' })
+  ok(r.ok === true, 'a run succeeds (P0 context)')
+  ok(typeof r.scriptAbs === 'string' && r.scriptAbs.length > 0, '★ the return carries an ABSOLUTE scriptAbs (members can open it directly)')
+  ok(typeof r.cwd === 'string' && r.cwd.length > 0, '★ the return carries cwd (the project root to join with)')
+  ok(String(r.scriptAbs).replace(/\\/g, '/').endsWith(String(r.scriptPath).replace(/\\/g, '/')), '★ scriptAbs ends with the receipt-relative scriptPath (join consistency)')
+  ok(!!h.files && h.files.has(String(r.scriptPath).replace(/\\/g, '/')), '★ the archived script really exists at scriptPath (the path handed to members is real)')
+  const rj = JSON.parse(h.files.get(String(r.receipt.json).replace(/\\/g, '/')))
+  ok(rj.scriptAbs === r.scriptAbs && rj.cwd === r.cwd, 'the RECEIPT carries scriptAbs + cwd too (a later reader can reconstruct the location)')
+  ok(String(M.MATH_ARCHIVE_WORKFLOW_LINE).indexOf('receipt.scriptAbs') !== -1 && String(M.MATH_ARCHIVE_WORKFLOW_LINE_EN).indexOf('receipt.scriptAbs') !== -1, 'the injected archive rule tells members HOW to open the script (zh+en)')
+  ok(/会话 cwd/.test(String(M.MATH_ARCHIVE_WORKFLOW_LINE)) && /SESSION CWD/.test(String(M.MATH_ARCHIVE_WORKFLOW_LINE_EN)), 'the rule states the session-cwd resolution fact (zh+en)')
+}
+
+// ── 23. round-9 (real-engine): an engine INSTALLED but not on PATH must still be discovered
+// R 4.6.1 went to `C:\Program Files\R\R-4.6.1\bin` without touching PATH, so `probe` used to say R
+// was missing even though it was installed.
+{
+  const absTree = {
+    'C:/Program Files/R': [{ name: 'R-4.6.1', type: 'directory' }],
+    'C:/Program Files/R/R-4.6.1/bin': [{ name: 'Rscript.exe', type: 'file' }, { name: 'R.exe', type: 'file' }],
+  }
+  const h = makeFakeHost({ installed: [], absTree: absTree, runtimeRoots: [] })
+  M.registerMathComputation(h.host)
+  const p = await h.call({ op: 'probe', engine: 'r' })
+  ok(p.ok === true && p.engine === 'r', '★ a Rscript that exists ONLY in the default install dir is discovered (not on PATH)')
+  ok(!!p.engineInfo && /Program Files\/R\/R-4\.6\.1\/bin\/Rscript/.test(String(p.engineInfo.path)), 'the discovered path is the versioned install dir (' + String(p.engineInfo && p.engineInfo.path).slice(0, 60) + ')')
+}
+// ── 24. round-9 (real-engine): never suggest an install command that cannot run on this machine
+{
+  const h = makeFakeHost({ installed: [] })   // `winget` is NOT resolvable here
+  M.registerMathComputation(h.host)
+  const p = await h.call({ op: 'probe', engine: 'octave' })
+  ok(p.ok === false && p.code === 'MATH_ENGINE_NOT_FOUND', 'a missing engine still fails with ENGINE_NOT_FOUND')
+  ok(!!p.next && p.next.kind === 'user-install', 'the guidance is still user-install shaped')
+  ok(String(p.next.command) === '', '★ no runnable-looking command when its package manager is absent (command is empty)')
+  ok(!/winget|brew|apt|choco|scoop/i.test(String(p.next.command) + ' ' + String(p.message)), '★ no winget/brew/apt suggestion anywhere when that manager is absent')
+  ok(p.next.packageManager === 'winget' && p.next.packageManagerAvailable === false, 'the response SAYS which manager was assumed and that it is unavailable')
+  ok(typeof p.next.note === 'string' && p.next.note.length > 0, 'an explicit note explains that the suggested command cannot run')
+  const h2 = makeFakeHost({ installed: [], resolveMap: { winget: 'C:/fake/winget.exe' } })
+  M.registerMathComputation(h2.host)
+  const p2 = await h2.call({ op: 'probe', engine: 'octave' })
+  ok(/winget/i.test(String(p2.next.command)) && p2.next.packageManagerAvailable === true, 'when the manager IS present the command is offered as before')
+}
+
+// ── 25. round-9 F3/F5/F7: probe completeness, uniform failure evidence, explicit constraint policy
+{
+  // F3: a partial availability line must NAME the configured-but-absent engines.
+  const h = makeFakeHost({ installed: ['python3'] })
+  M.registerMathComputation(h.host)
+  const p = await h.call({ op: 'probe', engine: 'python' })
+  ok(p.ok === true && Array.isArray(p.absent) && p.absent.length > 0, '★ probe names the configured-but-absent engines instead of being silently partial')
+  ok(p.absent.some((a) => a.engine === 'r' && a.why === 'not-found-on-this-machine'), 'the absent list carries a reason (key `why`) per engine')
+  ok(p.absent.some((a) => a.engine === 'cli' && /caller-supplied/.test(a.why)), 'cli is explained as needing a caller-supplied command')
+  ok(/未发现/.test(String(p.message)), 'the message states which configured engines were not found')
+  // F5: MATH_TIMEOUT carries the SAME evidence fields a non-zero exit does.
+  const h2 = makeFakeHost({ installed: ['python3'], hang: true })
+  M.registerMathComputation(h2.host)
+  const t = await h2.call({ op: 'run', engine: 'python', mode: 'code', code: 'while True: pass\n', timeoutMs: 1000 })
+  ok(t.ok === false && t.code === 'MATH_TIMEOUT', 'a hanging run reports MATH_TIMEOUT')
+  ok(t.timedOut === true && 'exit' in t && t.exit === null, '★ MATH_TIMEOUT carries timedOut:true and an explicit exit field (uniform with NONZERO_EXIT)')
+  ok('stderr' in t && typeof t.stderr === 'string', '★ MATH_TIMEOUT carries the captured stderr like NONZERO_EXIT does')
+  // F7: the response says the constraints are existence-only, and lists the ones that were NOT checked.
+  const h3 = makeFakeHost({ installed: ['python3'], packages: { numpy: 'present' } })
+  M.registerMathComputation(h3.host)
+  const c = await h3.call({ op: 'run', engine: 'python', mode: 'code', code: 'print(1)\n', packages: ['numpy>=1'] })
+  ok(c.ok === true && /existence-only/.test(String(c.versionPolicy)), '★ the run response states the version constraints are existence-only')
+  ok(Array.isArray(c.constraintsNotEnforced) && c.constraintsNotEnforced.indexOf('numpy>=1') !== -1, '★ the response names the constraint it did NOT check (no silent drop)')
+  const c2 = await h3.call({ op: 'run', engine: 'python', mode: 'code', code: 'print(1)\n', packages: ['numpy'] })
+  ok(Array.isArray(c2.constraintsNotEnforced) && c2.constraintsNotEnforced.length === 0, 'an unconstrained request reports an empty not-enforced list')
+  const m = await h3.call({ op: 'run', engine: 'python', mode: 'code', code: 'print(1)\n', packages: ['pandas>=2'] })
+  ok(m.ok === false && /existence-only/.test(String(m.versionPolicy)), 'the missing-package failure also states the constraint policy')
+}
+
+// ── 26. round-9 (N1): edited-archived-script evidence integrity
+// The documented P2a flow: edit the ORIGINAL source, re-run mode:'file' ⇒ SAME archive id, attempt>=2,
+// scriptChanged:true, previousReceipt at the prior attempt, prior attempt untouched. Pointing mode:'file'
+// at an ARCHIVED script is a NEW archive id by design (the id is keyed by the SOURCE PATH) - which must
+// be SAID (fileIsArchivedScript + a warning), not look like broken change detection.
+{
+  const h = makeFakeHost({ installed: ['python3'], files: { 'Problems/x.py': 'print(1)\n' } })
+  M.registerMathComputation(h.host)
+  const r1 = await h.call({ op: 'run', engine: 'python', mode: 'file', file: 'Problems/x.py' })
+  ok(r1.ok === true && r1.attempt === 1 && r1.scriptChanged === false, 'first run of a source file: attempt 1, no change')
+  const rj1 = JSON.parse(h.files.get(String(r1.receipt.json).replace(/\\/g, '/')))
+  ok(typeof r1.runId === 'string' && rj1.runId === r1.runId, '★ the run response exposes its archive id (matches the durable receipt.runId) - needed to check "same archive id"')
+  h.files.set('Problems/x.py', 'print(2)\n')
+  const r2 = await h.call({ op: 'run', engine: 'python', mode: 'file', file: 'Problems/x.py' })
+  ok(r2.ok === true && r2.runId === r1.runId, '★ editing the ORIGINAL source and re-running lands on the SAME archive id')
+  ok(r2.attempt >= 2 && /\/attempts\/\d+/.test(String(r2.attemptDir || '')), '★ the re-run is attempt>=2 under attempts/<n>/')
+  ok(r2.scriptChanged === true, '★ the re-run reports scriptChanged:true')
+  ok(!!r2.previousReceipt && r2.previousReceipt.attempt === r1.attempt && r2.previousReceipt.scriptHash === r1.scriptHash, '★ previousReceipt points at the prior attempt (attempt + scriptHash)')
+  ok(h.files.get(String(r1.scriptPath).replace(/\\/g, '/')) === 'print(1)\n', '★ the prior attempt\'s script is NOT overwritten (append-only)')
+  // A DIFFERENT source path (e.g. a copy of the old script, or a brand-new file) is a NEW archive id BY
+  // DESIGN: the id is keyed by the source path, so there is no history for that id and
+  // scriptChanged/previousReceipt are - correctly - empty. This is the case a finder can mistake for
+  // "broken change detection"; it is not, and the docs now say so.
+  h.files.set('Problems/copy_of_old.py', 'print(1)\n')
+  const r3 = await h.call({ op: 'run', engine: 'python', mode: 'file', file: 'Problems/copy_of_old.py' })
+  ok(r3.ok === true, 'a run of a different source path succeeds (' + JSON.stringify({ ok: r3.ok, code: r3.code }) + ')')
+  ok(r3.runId !== r1.runId, '★ a DIFFERENT source path gets a DIFFERENT archive id')
+  ok(r3.attempt === 1, '★ …and therefore starts at attempt 1 (fresh archive, by design)')
+  ok(r3.scriptChanged === false, '★ …and reports scriptChanged:false (no history FOR THIS id)')
+  ok(r3.previousReceipt === null || r3.previousReceipt === undefined, '★ …and has no previousReceipt (expected, not broken change detection)')
+  ok(h.files.get(String(r1.scriptPath).replace(/\\/g, '/')) === 'print(1)\n', 'the earlier attempt is still untouched after that run')
+}
+// ── 27. round-9 (N2): a TIMEOUT carries its partial output in BOTH the response and the receipt
+{
+  const h = makeFakeHost({ installed: ['python3'], hang: true, stdoutBytes: 16 })
+  M.registerMathComputation(h.host)
+  const t = await h.call({ op: 'run', engine: 'python', mode: 'code', code: 'print("before-timeout")\n', timeoutMs: 1000 })
+  ok(t.ok === false && t.code === 'MATH_TIMEOUT', 'the hanging run reports MATH_TIMEOUT')
+  ok('stdout' in t && 'stderr' in t, '★ the TIMEOUT response carries stdout AND stderr (not just the archived file)')
+  const rj = JSON.parse(h.files.get(String(t.receipt.json).replace(/\\/g, '/')))
+  ok(typeof rj.partialStdout === 'string' && typeof rj.partialStderr === 'string', '★ the TIMEOUT receipt JSON carries the capped partial output (as strings)')
+}
+
 console.log('')
 console.log('=== MATH COMPUTATION SHARED: ' + passed + ' passed, ' + failed + ' failed ===')
 if (failures.length) for (const f of failures) console.error('  - ' + f)

package/vibe-math-v2/agent.cordis.yml

@@ -41,7 +41,8 @@
         mode.
 
       - math_computation {op: probe|run|receipt|install, engine, mode: code|file|expr, …} — 先 probe 预检引擎/包/许可，再调引擎计算并把脚本与输出归档成可复核回执；缺引擎/缺包只报告与给安装指引/计划；shell 兜底不算归档。
-      - 归档→编辑→重跑：mode:'code' 的脚本原件在回执的 scriptPath（Computation/<id>/script.<ext>），你可以用普通文件工具打开并编辑它；编辑后用 mode:'file' 指向它重跑，会写出一份**新回执/新 attempt**（含新的 scriptHash）。**旧回执对修改后的代码无效**——报告里必须引用与当前代码哈希一致的那份回执；工具会在 scriptChanged / scriptChangedDuringRun 为 true 时显式告警。
+      - 替代必须声明（诚实性）：当替代方案改变了**精确性或结论强度**时（精确符号解 → 数值近似、闭式解 → 采样/求积、改了精度/容差/假设、换了算法类），结论里**必须写明**，不得读起来像得到了原本（精确/所要求的）结果；拿不到精确结果就直说。
+      - 归档→编辑→重跑：mode:'code' 的脚本原件在回执的 scriptPath（Computation/<id>/script.<ext>，**相对项目根**）；**成员的文件工具是按会话 cwd 解析的**，所以打开它要用**绝对路径** `receipt.scriptAbs`，或把 `receipt.cwd` 与 `receipt.scriptPath` 拼起来（回执两个字段都有）；编辑后用 mode:'file' 指向它重跑，会写出一份**新回执/新 attempt**（含新的 scriptHash）。**旧回执对修改后的代码无效**——报告里必须引用与当前代码哈希一致的那份回执；工具会在 scriptChanged / scriptChangedDuringRun 为 true 时显式告警。
 
       Final paper: strict termination writes Paper/<project>/{paper.md,paper.tex,paper.pdf,paper.meta.json,paper.log.md}
       automatically — a dedicated paper-writing child assembles the solved material (finalPaper=false disables only that
@@ -118,7 +119,8 @@
         mode.
 
       - math_computation {op: probe|run|receipt|install, engine, mode: code|file|expr, …} — 先 probe 预检引擎/包/许可，再调引擎计算并把脚本与输出归档成可复核回执；缺引擎/缺包只报告与给安装指引/计划；shell 兜底不算归档。
-      - 归档→编辑→重跑：mode:'code' 的脚本原件在回执的 scriptPath（Computation/<id>/script.<ext>），你可以用普通文件工具打开并编辑它；编辑后用 mode:'file' 指向它重跑，会写出一份**新回执/新 attempt**（含新的 scriptHash）。**旧回执对修改后的代码无效**——报告里必须引用与当前代码哈希一致的那份回执；工具会在 scriptChanged / scriptChangedDuringRun 为 true 时显式告警。
+      - 替代必须声明（诚实性）：当替代方案改变了**精确性或结论强度**时（精确符号解 → 数值近似、闭式解 → 采样/求积、改了精度/容差/假设、换了算法类），结论里**必须写明**，不得读起来像得到了原本（精确/所要求的）结果；拿不到精确结果就直说。
+      - 归档→编辑→重跑：mode:'code' 的脚本原件在回执的 scriptPath（Computation/<id>/script.<ext>，**相对项目根**）；**成员的文件工具是按会话 cwd 解析的**，所以打开它要用**绝对路径** `receipt.scriptAbs`，或把 `receipt.cwd` 与 `receipt.scriptPath` 拼起来（回执两个字段都有）；编辑后用 mode:'file' 指向它重跑，会写出一份**新回执/新 attempt**（含新的 scriptHash）。**旧回执对修改后的代码无效**——报告里必须引用与当前代码哈希一致的那份回执；工具会在 scriptChanged / scriptChangedDuringRun 为 true 时显式告警。
 
       Final paper: strict termination writes Paper/<project>/{paper.md,paper.tex,paper.pdf,paper.meta.json,paper.log.md}
       automatically — a dedicated paper-writing child assembles the solved material (finalPaper=false disables only that