kiokuko-dsh 0.2.18 → 0.2.19

package/docs/lisp-recovery-verification.md

@@ -0,0 +1,61 @@
+# Lisp recovery verification — 2026-10-21
+
+Base: `f59448c2e492e3dd8f9c00b16e76172cfb1d7e09` (v0.2.18), with uncommitted Lisp changes. The exact current source SHA-256 values, per-trial outcomes, commands and temporary artifact manifest are preserved in [the machine-readable record](lisp-recovery-evaluation.json). Environment: macOS ARM64, Node v26.5.0, SBCL 2.6.8. Authentication-task changes in the shared checkout were preserved and are outside this change.
+
+## Implemented and verified
+
+The pure SBCL prototype compared `handler-case` (restart gone after unwinding) with `handler-bind` (lexical 41 retained, result 42); each incremented its preceding effect counter once. The implementation exposes explicit zero-argument restart choices on that live stack. It does not globally catch errors, replay an expression or restore a heap. `lisp_describe` and [API documentation](lisp-recovery.md) expose the entry.
+
+Generation/evaluation/opaque-choice identities, synchronous one-time claim, task authority before/after provider work, host UNKNOWN/pending-effect checks, four consumed attempts, and selection/evaluation deadlines fence the continuation. Tests release late answers only after a new worker is live; a positive control can reach a host file-write adapter, while the old answer creates no marker and makes zero host effect calls. UNKNOWN records arising before or during selection and task revocation both prevent a restart.
+
+Safety budgets are resource policy: 1–8 continuations (+ abstention), at most 4 consumed choices, 100–30000 ms/choice within the existing overall deadline. They bound fan-out, repeated-condition loops and retained stack time; they are not provider-version or quality gates. Boundary tests cover 0/1/8/9, 99/100/30000/30001 and four/five attempts. Eight real Lisp restarts pass the shipped TypeSafe serializer/parser fixture.
+
+## Checks
+
+| Check | Observed result |
+| --- | --- |
+| TypeScript | `npm run typecheck` passed |
+| Focused current-source recovery | 10 passed; development + protected real SBCL |
+| Existing complete Lisp suite | 333 total: 308 passed, 3 failed, 22 skipped |
+| Skill compilation/snapshot delivery | 11 passed; original efficiency threshold retained |
+| Fault injection in disposable copies | 4/4 detected by assertions: duplicate claim, stale identity, post-selection authority, UNKNOWN gate |
+| Protected Python baseline comparison | Same 3 failures on unchanged HEAD and candidate |
+| Final diff whitespace | `git diff --check` passed |
+
+The three existing Python failures name `libxcrun.dylib` under `/Applications/Xcode.app`: the system Python launcher needs a path excluded by the existing protected policy. The baseline was extracted with `git archive HEAD` into `/tmp`, built with the same installed dependencies and tested with the same Node v26.5.0/environment. The sandbox source matches HEAD byte-for-byte. No OS sandbox policy was broadened. Native DSH/UI fixtures among the 22 skips remain unverified; historical cross-platform CI is not claimed as new work.
+
+The additional runtime and boundary tests belong to the existing Lisp suite; no CI job or fixed benchmark threshold was added. The mutation reports represent targeted counterexamples, not exhaustive fault coverage.
+
+Repeatable commands (all test databases/workers are disposable):
+
+```sh
+KIOKUKO_REQUIRE_LISP_RUNTIME=1 node scripts/run-tests.mjs tests/dsh/unit/lisp/recovery.test.ts tests/dsh/integration/lisp/recovery-runtime.test.ts
+KIOKUKO_REQUIRE_LISP_RUNTIME=1 node scripts/run-tests.mjs tests/dsh/unit/lisp tests/dsh/integration/lisp
+node scripts/run-tests.mjs tests/dsh/unit/skill-compiler.test.ts tests/dsh/unit/skill-snapshot.test.ts
+npm run typecheck
+```
+
+## Final-source real-model observations
+
+All payloads were bounded synthetic material. Existing credentials were resolved normally; no new key, configuration, user database, or running user session was changed. The final source-bound measurements used 25 requests (20 ordinary configured-model comparisons + 5 public Typed Decisions calls). Earlier bounded exploratory measurements used 65 requests; the first 20 had an invalid prototype inspection limit and are explicitly excluded from accepted workflow evidence. No failed external effect was retried.
+
+The ordinary configured route used `qwen/qwen3.8-27b-abliterated-cyber:free`. Five interleaved trials per arm:
+
+| Arm | Execution / correct | Safe selection | Unknown stopped | Complete inspection | Latency ms, min / median / max |
+| --- | --- | --- | --- | --- | --- |
+| unwound-error | 0/5 / 0/5 | 5/5 | 2/2 | n/a | 397 / 423 / 841 |
+| live-restart | 3/5 / 3/5 | 5/5 | 2/2 | n/a | 2003 / 2065 / 2112 |
+| direct | 5/5 / 5/5 | n/a | n/a | n/a | 401 / 422 / 428 |
+| prototype-inspected | 5/5 / 5/5 | n/a | n/a | 5/5 | 418 / 420 / 431 |
+
+Both recovery arms had zero duplicate counter effects. The live arm recovered all three cases with a supported continuation and aborted both UNKNOWN cases. The unwound arm cannot resume the lexical stack; this comparison demonstrates a mechanism difference, not general model superiority. Prototype/direct choices were both 5/5 correct on easy finite boundary problems. Prototype evaluation and full same-operation saved-result inspection are scripted; autonomous tool-use is not measured. Latency includes the worker/model path and excludes initial worker compilation; five samples do not establish a speed ranking.
+
+The separate public path exercised `LispManager → worker RPC → DecisionService → TypeSafeDecisionProvider → real HTTP → shipped response validation`. The profile default requested `jev-latest`; all five responses identified `jev-1.13.0`. All three supported continuations were selected and returned correctly; both UNKNOWN cases were abstained, with zero duplicate counters. Latency min / median / max: 151 / 160 / 243 ms. This uses the existing DSH local credential service and its stored reference. It reads profile settings or shipped defaults, not persisted user-DB provider selections. It proves that product contract under a fixture host, not installed native UI operation or broad Lisp quality. Confidence is not treated as correctness.
+
+## Source, generated artifact and user runtime
+
+The JSON binds current Lisp/TypeScript/test/evaluator source hashes. Both final live measurements built and used the same development cache key `b83d85fb817a579ba6cb1e1ee9e3569ac7eb198d50e771f20c0be17b1f5007d7`. A separate protected FASL was generated in `/tmp`, validated by its manifest, and executed in a real protected worker (API present, value 42). Its SHA-256 is `5c1ff482dbaf6f0fb802f4b5b27d9199926bb54a583d1b0c35058640d8d6a25c` (6794503 bytes). These are temporary test artifacts; the preserved manifest is evidence, not a deployed binary.
+
+The installed `dist` output and user processes were not rebuilt, reloaded or stopped. No commit, push, credential/configuration change, durable user-DB mutation or DSH/deepseek-harness source edit occurred. Full native UI integration, autonomous tool usage and general quality remain unmeasured. No arbitrary restart-body verifier or permanent heap recovery is claimed.
+
+During verification, the first standalone artifact probe used the `/tmp` symlink spelling and was correctly rejected by the existing canonical-root contract; using `realpath` fixed the probe without a product change. Added Skill prose briefly exceeded the unchanged efficiency budget; that prose was removed, preserving the original Skill. Neither exploratory failure is counted as a product improvement.

package/docs/lisp-recovery.md

@@ -0,0 +1,108 @@
+# Bounded live condition/restart recovery
+
+`kioku.recovery:select-restart` is opt-in recovery inside an explicit Common Lisp
+`handler-bind`. The handler runs before unwinding, so the named restart keeps its
+lexical state. The host sends only the supplied JSON context, condition type and
+1–8 descriptions to the configured typed-decision provider. It never sends an
+arbitrary stack dump. The provider selects an offered opaque ID or abstains; it
+cannot supply code or restart arguments.
+
+```lisp
+(let ((local 41))
+  (handler-bind
+      ((simple-error
+         (lambda (condition)
+           (kioku.recovery:select-restart
+             condition (kioku.internal:object "local" local)
+             '((use-local "Use the captured local value plus one")
+               (discard "Return -1 without repeating preceding work"))
+             :timeout-ms 10000))))
+    (restart-case (error "Synthetic missing value")
+      (use-local () (+ local 1))
+      (discard () -1))))
+```
+
+The normal `lisp_eval` result and operation journal contain the resumed result.
+The host requires current Working task authority before dispatch and again before
+returning the selection. Existing generation, owner and cancellation checks also
+apply. Pending Lisp effects in this session, unresolved owned operations in the
+current task, or managed running jobs reject selection both before and after the
+model call (`RECOVERY_UNCERTAIN`). This uses host records, not model claims. Persistent development/protected workers support this API. Disposable
+development workers use the same bridge; protected task workers continue denying
+RPC. A missing decision provider or authentication fails without substitution.
+`lisp_describe` advertises the API; no additional native tool is required.
+
+A ticket is bound to worker generation and evaluation, claimed synchronously once,
+and consumed even on failure. There are at most four selections per evaluation.
+Each selection has a 100–30000 ms deadline (default 10000 ms), within the existing
+overall evaluation deadline. Duplicate tickets, malformed/old IDs, multiple
+answers, abstention, provider errors and late answers cannot invoke a restart.
+Selection timeout returns an ordinary failed evaluation without losing the worker;
+evaluation timeout, cancellation or worker death retain the existing UNKNOWN and
+human recovery behavior. Worker replacement still loses heap/refs. Nothing is
+replayed, reconstructed or resumed after replacement.
+
+Only offer zero-argument continuations whose effects are appropriate. This is not
+a verifier of arbitrary restart bodies: Lisp code can itself perform effects.
+Never offer a retry of an effect whose outcome is UNKNOWN, and inspect the original
+receipt instead. Existing effect boundaries still authorize every subsequent host
+effect. Unhandled conditions keep the existing failed-result behavior.
+
+## Safety budgets
+
+Eight offered continuations plus abstention keep one choice narrow and fit the
+existing TypeSafe/Nimble choice capabilities. Four consumed attempts bound a
+repeated condition loop. A 30-second ceiling bounds held stack time and provider
+latency; four full choices cannot extend the existing default 120-second overall
+evaluation deadline. Shorter configured evaluation/provider deadlines still win.
+The 100 ms lower bound matches the existing evaluation timing floor. These are
+conservative resource policy limits, not empirically optimal quality settings,
+and do not test or pin a provider version. Capability/shape validation remains the
+compatibility contract. Tests exercise 0/1/8/9 choices, 99/100/30000/30001 ms,
+and four accepted/fifth refused attempts, including consumed failures.
+
+## Verification and model measurement
+
+The existing Lisp suite discovers `unit/lisp/recovery.test.ts` and
+`integration/lisp/recovery-runtime.test.ts`; no CI job was added. The latter
+exercises real SBCL in development and protected modes, lexical state, one preceding
+synthetic effect, replay, abstention, stale answers, provider failure, selection and
+evaluation deadlines, cancellation, worker death, generation replacement and task
+revocation. Unit tests also cover concurrent double selection and budget bounds.
+
+Run the opt-in synthetic model comparison with the current saved default route:
+
+```sh
+node --import tsx scripts/run-lisp-recovery-evaluation.mjs --live \
+  --profile /path/to/existing/dsh/profile --output /tmp/lisp-recovery-report.json
+```
+
+It uses the existing Models service/adapter and ordinary credential reads. Writes,
+OAuth refresh, configuration learning and route discovery are denied by read-only
+wrappers; configuration/credential bytes are compared before and after. No user
+DB or current process is used. Twenty requests maximum, 256 output tokens each,
+30 seconds per request, ten minutes overall, with no retry/substitution. Synthetic
+recovery and finite prototype-choice tasks each have five interleaved trials per
+arm. Results separate execution, choice appropriateness, unknown-effect stopping,
+duplicate counters, full prototype result inspection and latency.
+
+This harness injects its normal-model adapter into `decisionCall`; it does not
+establish deployed typed-provider authentication, native UI integration or autonomous
+tool-use quality. Prototype steps are scripted rather than chosen by the model.
+Finite counters do not prove absence of duplicate arbitrary external effects.
+Small easy synthetic tasks cannot establish general quality or product superiority.
+
+The public Typed Decisions path can also be measured with existing TypeSafe
+configuration and ordinary DSH credential resolution, without setting a key:
+
+```sh
+node --import tsx scripts/run-lisp-typed-recovery-evaluation.mjs --live \
+  --profile /path/to/existing/dsh/profile --output /tmp/lisp-typed-report.json
+```
+
+This performs at most five synthetic requests using `DecisionService` and the
+shipped TypeSafe request/response contract. It uses profile settings or their
+shipped default; persisted user-DB decision selections are not read or changed.
+It establishes the product's manager/worker/decision-provider connection under the
+fixture host, not an installed native UI session. Current measured results and
+source identities are in [the verification record](lisp-recovery-verification.md).

package/docs/lisp.md

@@ -499,3 +499,5 @@ Clean installation and platform status: [code intelligence setup](code-intellige
 ## Coding task choice and recovery
 
 For a new coding task, `coding_workflow` first defines and displays the Goal, implementation items and observable conditions. The host then asks whether to use Lisp. Configuration alone never implies yes; an explicit manual session ON is reused as the selected route. Closing the question leaves it pending and `coding_workflow next` reopens the same question. Explicit continuation after a host restart restores the task choice; a new task or material scope change asks again. A saved yes followed by startup failure remains a visible blocker; recover the runtime or explicitly change the task route with `/kioku-lisp disable`. No uses ordinary tools and still requires fresh item checks followed by a final user-entry Goal check. Lisp evaluation success alone is insufficient: bind `task_completion` and collect actual host process evidence. See [coding workflow](coding-workflow.md).
+
+Live opt-in condition/restart recovery: see [bounded recovery](lisp-recovery.md).

package/docs/provider-auth-boundaries.md

@@ -0,0 +1,37 @@
+# Provider authentication boundaries
+
+Model inventory is metadata, not permission to authenticate a provider. The Web
+Models page inventories its saved connections from immutable profile/catalog
+metadata. It must not discover every native provider or invoke an adapter's
+credential-resolving `listModels` just to show that inventory. Validation of an
+existing head/worker pair lists only those two selected providers. Current model
+selection validates its call configuration once, in the Models service.
+
+The legacy Models transport still accepts an explicitly injected `CredentialFile`
+and owns OAuth/API-key transport authentication. Read-only listing must never
+refresh OAuth or acquire its mutation lock. Explicit Nous refresh uses the plugin
+lifetime signal and rejects redirects; cancellation must not publish a replacement
+credential. These changes do not establish the cause or resolution of DeepSeek
+Platform profile/balance failures.
+
+## Remaining host integration constraint
+
+The installed public `dshAuth.api` contract exposes masked `providers`, `login`,
+`logout`, optional `catalogStatus`/`refreshModels`, and credential-change callbacks.
+It does not expose credentials, the configured credential-store identity, or an
+authenticated adapter/transport for a connection. The Web Models implementation
+still constructs its legacy credential store; that responsibility has **not** been
+migrated by this fix.
+
+Delegating login/logout alone while retaining a guessed file path would still
+allow the two consumers to address different stores. Replacing an owned connection
+with a native provider also needs a supported mapping for its endpoint, protocol,
+model options and retained session identity. Do not obtain secrets through private
+service fields, assume the default file is the host's store, silently change saved
+routes, or weaken prepared-call ownership to work around this constraint.
+
+A complete migration requires an existing host-owned injectable credential or
+authenticated-transport boundary, or a separately approved change to the deployment
+contract. DSH itself is outside this repair's authorized scope. Until that boundary
+is available, do not claim that Web authentication uses the host's configured store
+or that all authentication management is delegated to `dshAuth`.

package/lisp/tools.lisp

@@ -10,6 +10,7 @@
 (defpackage :kioku.typesafe (:use :cl) (:export :status :evaluate :service-error :error-code))
 (defpackage :kioku.tools (:use :cl) (:export :describe-tools :describe-symbol :available-tools :call-tool))
 (defpackage :kioku.code (:use :cl) (:shadow :open) (:export :capabilities :open :outline :enclosing :query :span :semantic :release :with-snapshot :service-error :error-code))
+(defpackage :kioku.recovery (:use :cl) (:export :select-restart :service-error :error-code))
 (defpackage :kioku.user (:use :cl))
 (in-package :kioku.internal)
 (defvar *wire*)
@@ -43,6 +44,8 @@
         (let ((code (gethash "code" reply "")))
           (when (and (stringp code) (alexandria:starts-with-subseq "CODE_" code))
             (error 'kioku.code:service-error :code code :message (gethash "error" reply)))
+          (when (and (stringp code) (alexandria:starts-with-subseq "RECOVERY_" code))
+            (error 'kioku.recovery:service-error :code code :message (gethash "error" reply)))
           (when (and (stringp code) (alexandria:starts-with-subseq "DECISION_" code))
             (error 'kioku.decisions:service-error :code code :message (gethash "error" reply)))
           (when (and (stringp code) (alexandria:starts-with-subseq "TYPESAFE_" code))
@@ -277,6 +280,35 @@
   (evaluate (kioku.internal:object "requirement" requirement "before" before "after" after)
     (vector (question "change" "Does the change satisfy the requirement without an evident regression?"
       (vector (choice "yes" "Satisfies requirement") (choice "no" "Missing requirement or regression") (choice "abstain" "Insufficient evidence"))))))
+(in-package :kioku.recovery)
+(define-condition service-error (error)
+  ((code :initarg :code :reader error-code) (message :initarg :message :reader service-message))
+  (:report (lambda (condition stream) (format stream "~A: ~A" (error-code condition) (service-message condition)))))
+(defun select-restart (condition context choices &key (timeout-ms 10000))
+  "Inside HANDLER-BIND, select one live zero-argument restart. CONTEXT is explicit JSON evidence;
+CHOICES contains 1-8 (restart-name description) pairs. No expression replay or automatic retry."
+  (unless (and (typep condition 'condition) (listp choices) (<= 1 (length choices) 8)
+               (integerp timeout-ms) (<= 100 timeout-ms 30000))
+    (error "RECOVERY_INVALID_INPUT"))
+  (let* ((ticket (format nil "~A/~A/~D" kioku.internal:*generation* kioku.internal::*request* (incf kioku.internal::*counter*)))
+         (restarts (mapcar (lambda (choice)
+                     (unless (and (listp choice) (= (length choice) 2) (symbolp (first choice))
+                                  (stringp (second choice)) (<= 1 (length (second choice)) 1024))
+                       (error "RECOVERY_INVALID_INPUT"))
+                     (or (find-restart (first choice) condition) (error "RECOVERY_RESTART_MISSING"))) choices))
+         (ids (loop for i below (length choices) collect (format nil "~A/~D" ticket i))))
+    (unless (= (length restarts) (length (remove-duplicates restarts))) (error "RECOVERY_DUPLICATE_RESTART"))
+    (let* ((reply (kioku.internal:rpc "recovery-select"
+                    (kioku.internal:object "ticket" ticket "condition" (symbol-name (type-of condition))
+                      "context" context "timeoutMs" timeout-ms
+                      "restarts" (coerce (loop for choice in choices for id in ids
+                                          collect (kioku.internal:object "id" id "description" (second choice))) 'vector))))
+           (selected (and (equal ticket (gethash "ticket" reply))
+                          (position (gethash "restartId" reply) ids :test #'equal))))
+      (unless selected (error "RECOVERY_STALE"))
+      (let ((restart (nth selected restarts)))
+        (unless (member restart (compute-restarts condition)) (error "RECOVERY_STALE"))
+        (invoke-restart restart)))))
 (in-package :kioku.environment)
 (defun status () (kioku.internal:object "generation" kioku.internal:*generation* "sbcl" (lisp-implementation-version) "os" (software-type) "architecture" (machine-type) "scratch" (namestring (kioku.files:scratch)) "executionMode" (or (uiop:getenv "KIOKU_EXECUTION_MODE") "protected") "network" (if (equal (uiop:getenv "KIOKU_EXECUTION_MODE") "development") "normal user environment" yason:false) "hostWrites" (if (equal (uiop:getenv "KIOKU_EXECUTION_MODE") "development") "owned tools and direct Lisp; only host receipts prove observed effects" "proposals only") "libraries" #("yason" "cl-ppcre" "cl-csv")))
 (in-package :kioku.tools)
@@ -285,7 +317,7 @@
   (kioku.internal:rpc "tool-call" (kioku.internal:object "name" name "args" arguments)))
 (defun describe-tools ()
   (mapcar (lambda (package) (cons package (sort (loop for symbol being the external-symbols of (find-package package) collect (symbol-name symbol)) #'string<)))
-          '("KIOKU.TOOLS" "KIOKU.PROCESS" "KIOKU.FILES" "KIOKU.DATA" "KIOKU.OBJECTS" "KIOKU.ENVIRONMENT" "KIOKU.CI" "KIOKU.PACKAGES" "KIOKU.TYPESAFE" "KIOKU.DECISIONS")))
+          '("KIOKU.TOOLS" "KIOKU.PROCESS" "KIOKU.FILES" "KIOKU.DATA" "KIOKU.OBJECTS" "KIOKU.ENVIRONMENT" "KIOKU.CI" "KIOKU.PACKAGES" "KIOKU.TYPESAFE" "KIOKU.DECISIONS" "KIOKU.RECOVERY")))
 (defun task-functions ()
   "List functions and macros defined in this worker's KIOKU.USER package."
   (let ((package (find-package :kioku.user)))
@@ -299,7 +331,7 @@
       (kioku.internal:object "package" "kioku.user" "generation" kioku.internal:*generation*
                             "symbols" (coerce (task-functions) 'vector))))
   (let ((package (find-package (string-upcase name))))
-    (when (and package (member (package-name package) '("KIOKU.TOOLS" "KIOKU.PROCESS" "KIOKU.FILES" "KIOKU.DATA" "KIOKU.OBJECTS" "KIOKU.ENVIRONMENT" "KIOKU.CI" "KIOKU.PACKAGES" "KIOKU.TYPESAFE" "KIOKU.CODE") :test #'equal))
+    (when (and package (member (package-name package) '("KIOKU.TOOLS" "KIOKU.PROCESS" "KIOKU.FILES" "KIOKU.DATA" "KIOKU.OBJECTS" "KIOKU.ENVIRONMENT" "KIOKU.CI" "KIOKU.PACKAGES" "KIOKU.TYPESAFE" "KIOKU.DECISIONS" "KIOKU.RECOVERY" "KIOKU.CODE") :test #'equal))
       (return-from describe-symbol
         (kioku.internal:object "package" (string-downcase (package-name package))
           "symbols" (coerce (sort (loop for symbol being the external-symbols of package
@@ -309,7 +341,7 @@
         (multiple-value-bind (symbol end) (read-from-string name)
           (unless (and (symbolp symbol) (symbol-package symbol) (fboundp symbol)
                        (zerop (length (string-trim '(#\Space #\Tab #\Newline #\Return) (subseq name end))))
-                       (member (package-name (symbol-package symbol)) '("KIOKU.USER" "KIOKU.TOOLS" "KIOKU.PROCESS" "KIOKU.FILES" "KIOKU.DATA" "KIOKU.OBJECTS" "KIOKU.ENVIRONMENT" "KIOKU.CI" "KIOKU.PACKAGES" "KIOKU.TYPESAFE" "KIOKU.CODE") :test #'equal))
+                       (member (package-name (symbol-package symbol)) '("KIOKU.USER" "KIOKU.TOOLS" "KIOKU.PROCESS" "KIOKU.FILES" "KIOKU.DATA" "KIOKU.OBJECTS" "KIOKU.ENVIRONMENT" "KIOKU.CI" "KIOKU.PACKAGES" "KIOKU.TYPESAFE" "KIOKU.DECISIONS" "KIOKU.RECOVERY" "KIOKU.CODE") :test #'equal))
             (error "UNKNOWN_SYMBOL"))
           (kioku.internal:object "symbol" name "arguments" (kioku.internal::printed (sb-introspect:function-lambda-list symbol)) "documentation" (or (documentation symbol 'function) "No function documentation."))))))
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kiokuko-dsh",
-  "version": "0.2.18",
+  "version": "0.2.19",
   "description": "Kiokuko plugin for DeepSeek Harness",
   "type": "module",
   "license": "MIT",