memleaf 0.2.80__tar.gz → 0.2.81__tar.gz

{memleaf-0.2.80 → memleaf-0.2.81}/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to memleaf are documented here.
 
 ## Unreleased
 
+## 0.2.81 — 2026-09-30
+
+### HTTP failure classification and controlled run recovery
+
+- Preserve safe numeric HTTP status in model errors, request attempts and
+  processing diagnostics. Allow 408/500/502/503/504 to use the remaining original
+  transport allowance; known permanent errors stay closed.
+- Add revision-bound failed automatic run preview/apply through the Python API,
+  `recover-run` CLI and `recover_failed_run` MCP tool. Historical unclassified
+  HTTP errors require explicit acknowledgement; ordinary recovery stays unchanged.
+- Rebuild current comparison context for unchanged sources while retaining run,
+  commit and budget identities, prior attempts and recovery audit. Reject consumed,
+  changed or revoked sources, conflicting ownership, exhausted budgets and full
+  active receipt capacity. Repeated execution and interrupted writes remain bounded.
+- Validation: 121 focused checks passed and 10 historical failed runs exercised
+  isolated recovery with an injected HTTP503, without network/model calls or
+  formal Vault changes. Real-model semantic quality remains unverified.
+
 ## 0.2.80 — 2026-09-29
 
 ### Explicit deadline annotations

{memleaf-0.2.80/src/memleaf.egg-info → memleaf-0.2.81}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memleaf
-Version: 0.2.80
+Version: 0.2.81
 Summary: A local-first Markdown memory core for AI agents
 Author: memleaf contributors
 License-Expression: MIT
@@ -23,7 +23,7 @@ Dynamic: license-file
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **版本：0.2.80。**
+> **版本：0.2.81。**
 > 自动提炼和复核共用同一条“未来记忆价值”标准：模型综合未来复用、信息增量、再次读取时的直接可用性和忘记成本，只保留对未来理解、判断或行动有实质影响的最小核心；没有明确价值的信息不提炼，不按具体业务场景硬编码排除。
 > 提炼契约现在只有一份中文语义契约（旧版英文 B3 提示词已删除），首轮、主题选择、候选修复和 `semantic_maintenance` 使用同一套保留价值判断；同一件事只写一次。
 > Core 不再因为归属、日期、任务依据或跨项目而丢弃整条候选：归属缺失会归一到证据里唯一被点名的项目、否则落 `global`；日期只接受能在本候选证据里找到出处、且能锚定成 ISO 的写法（`明天`、`周五`、`月底` 都会被解析），无法解析时只丢掉日期字段，记忆照常写入；未获授权的改归属沿用目标原归属。
@@ -280,6 +280,7 @@ python -m memleaf.mcp_server --vault "$HOME/.memleaf"
 | `read` | 使用当前 `retrieval_id` 分页读取选中的记忆正文 |
 | `process` | 处理完整 inbox 轮次并按准入规则提炼；`background=true` 时异步入队 |
 | `process_status` | 只读查询异步处理 job 状态 |
+| `recover_failed_run` | 预览并显式恢复终态传输失败，保留原请求预算 |
 | `remember` | 用户明确要求时创建或更新记忆 |
 | `forget_memory` | 按精确 ID 删除一条记忆 |
 | `forget_about` | 忘记明确主题；有歧义时只返回候选 |
@@ -529,3 +530,5 @@ memleaf process --vault /path/to/existing/vault --source hermes --session-id SES
 边界在宿主采集、Core capture 和历史 inbox 的新处理处执行。
 已提交记忆不会自动删除。旧版本已冻结但未完成的计划不会被静默丢弃或重新规划，
 不含新来源边界标记的计划会停止恢复并保留现场，避免越过新的输入约定。
+
+历史 HTTP 失败的受控恢复及 CLI 用法见 [失败任务恢复](docs/failed-run-recovery.md)。

{memleaf-0.2.80 → memleaf-0.2.81}/README.en.md

@@ -4,7 +4,7 @@
 
 [中文](README.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **Version: 0.2.80.**
+> **Version: 0.2.81.**
 > Automatic extraction and review share one future-value standard: the model weighs likely reuse, information gain, direct usability when read again, and the cost of forgetting. It keeps only the smallest core that can materially help future understanding, decisions, or actions; information without clear value is not extracted, and no business-specific exclusion rule is hard-coded.
 > A single Chinese semantic contract is sent for extraction, topic selection, candidate repair, and `semantic_maintenance`; the older English B3 prompt has been deleted and B3 remains only as a compatibility read format. One topic is written once.
 > Core no longer discards a whole candidate over ownership, dates, task basis or cross-project wording. A missing owner normalizes to the single project named by that candidate's own evidence, otherwise `global`. A deadline is accepted only when it appears in the candidate's own evidence and can be anchored to ISO (`明天`, `周五`, `月底` all resolve); when it cannot, only the date field is dropped and the memory is still written. An unauthorized ownership change keeps the target's existing scope.
@@ -516,3 +516,5 @@ The boundary is enforced by host capture, Core capture and new processing of his
 inbox records. Committed memories are not deleted automatically. Frozen operations without
 the conversation-only policy marker are not silently replayed or replanned; they remain
 available for inspection so the new input contract is not bypassed.
+
+Controlled historical HTTP recovery and CLI usage: [failed-run recovery](docs/failed-run-recovery.md).

{memleaf-0.2.80 → memleaf-0.2.81}/README.md

@@ -4,7 +4,7 @@
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **版本：0.2.80。**
+> **版本：0.2.81。**
 > 自动提炼和复核共用同一条“未来记忆价值”标准：模型综合未来复用、信息增量、再次读取时的直接可用性和忘记成本，只保留对未来理解、判断或行动有实质影响的最小核心；没有明确价值的信息不提炼，不按具体业务场景硬编码排除。
 > 提炼契约现在只有一份中文语义契约（旧版英文 B3 提示词已删除），首轮、主题选择、候选修复和 `semantic_maintenance` 使用同一套保留价值判断；同一件事只写一次。
 > Core 不再因为归属、日期、任务依据或跨项目而丢弃整条候选：归属缺失会归一到证据里唯一被点名的项目、否则落 `global`；日期只接受能在本候选证据里找到出处、且能锚定成 ISO 的写法（`明天`、`周五`、`月底` 都会被解析），无法解析时只丢掉日期字段，记忆照常写入；未获授权的改归属沿用目标原归属。
@@ -261,6 +261,7 @@ python -m memleaf.mcp_server --vault "$HOME/.memleaf"
 | `read` | 使用当前 `retrieval_id` 分页读取选中的记忆正文 |
 | `process` | 处理完整 inbox 轮次并按准入规则提炼；`background=true` 时异步入队 |
 | `process_status` | 只读查询异步处理 job 状态 |
+| `recover_failed_run` | 预览并显式恢复终态传输失败，保留原请求预算 |
 | `remember` | 用户明确要求时创建或更新记忆 |
 | `forget_memory` | 按精确 ID 删除一条记忆 |
 | `forget_about` | 忘记明确主题；有歧义时只返回候选 |
@@ -510,3 +511,5 @@ memleaf process --vault /path/to/existing/vault --source hermes --session-id SES
 边界在宿主采集、Core capture 和历史 inbox 的新处理处执行。
 已提交记忆不会自动删除。旧版本已冻结但未完成的计划不会被静默丢弃或重新规划，
 不含新来源边界标记的计划会停止恢复并保留现场，避免越过新的输入约定。
+
+历史 HTTP 失败的受控恢复及 CLI 用法见 [失败任务恢复](docs/failed-run-recovery.md)。

memleaf-0.2.81/docs/failed-run-recovery.md

@@ -0,0 +1,56 @@
+# HTTP 失败与历史任务恢复
+
+HTTP 传输层保留经过校验的数字 `http_status`，不保存响应正文、URL、请求头或密钥。
+408、500、502、503、504 可在原预算仍有余额时进入 `retryable`；429 使用现有
+限流处理。400、401、403、404、501 等不因新的 HTTP 分类而获得重试。
+缺少状态码的历史 `model_http_error` 保持终态，普通 `process --recover` 不会重开它。
+
+## 按 run_id 预览及执行
+
+```sh
+# 预览：只读，无模型调用。旧 HTTP 回执必须明确接受其状态码未知。
+memleaf recover-run --vault /path/to/vault --run-id inc-run-... \
+  --allow-legacy-http --json
+
+# 仅当 recoverable=true 时，使用此次预览返回的完整 expected_revision。
+memleaf recover-run --vault /path/to/vault --run-id inc-run-... \
+  --allow-legacy-http --apply --expected-revision PREVIEW_REVISION --json
+```
+
+`--allow-legacy-http` 不放行已知的永久 HTTP 错误，也不增加预算。执行使用当前
+Vault 配置的固定 API 模型路由；预览不解析模型路由、不初始化 Vault、不创建锁文件。
+MCP 对应工具为 `recover_failed_run`，参数为 `run_id`、`allow_legacy_http`、
+`apply`（默认 false）及 `expected_revision`。
+
+Python API：
+
+```python
+preview = service.recover_failed_run(run_id, allow_legacy_http=True)
+if preview["recoverable"]:
+    result = service.recover_failed_run(
+        run_id, dry_run=False, allow_legacy_http=True,
+        expected_revision=preview["expected_revision"],
+    )
+```
+
+## 恢复边界
+
+- 只处理自动捕获任务的已知第一次传输失败，原请求预算为已用 1、尚有余额。
+  显式 remember 的授权正文已清除时，不能借此重新取得保留授权。
+- 原轮必须完整且可处理，来源摘要及原预算身份必须一致。来源被删除、修改、禁录，
+  已有消费记录、自动提交、旧流程待提交计划或其他活动所有者时拒绝恢复。
+- 原 run_id、budget_id、turn_budget_id、commit identity 和第一次尝试记录全部保留。
+  执行在锁内绑定此次预览版本，并记录旧失败、旧来源窗口、旧快照及恢复时间。
+  不修改原额度、不新建 run、不删除旧回执。
+- 原请求正文已清除，因此执行根据当前记忆重新生成快照和请求。完整后续对话仅以
+  `use=context` 参与比较，不独立创建新事项，也不随本轮结算。已有日期、来源及
+  `stale_observation` 校验继续生效；不能证明安全的修改留下未解决项。
+- 预览后状态、预算、来源或比较目标变化，需要重新预览。绑定后的调用前/提交前
+  校验不允许再次悄悄更新快照。
+- 第二次请求仍先预留再派发。崩溃后的未知调用保守计入预算；重复 apply 使用同一
+  恢复绑定，完成后只返回旧回执。保存的回复/提交可在没有模型配置时恢复。
+- compact 回执重开需要一个可用 full 槽位；容量不足时预览明确拒绝，不能删除
+  回执来换取执行机会。
+
+真实模型可能输出 NO_MEMORY、NO_CHANGE、UPDATE、CREATE 或未解决项；入口可执行
+不等于模型语义正确，也不承诺所有历史内容都应保存。

{memleaf-0.2.80 → memleaf-0.2.81}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "memleaf"
-version = "0.2.80"
+version = "0.2.81"
 description = "A local-first Markdown memory core for AI agents"
 readme = "README.md"
 requires-python = ">=3.11"

{memleaf-0.2.80 → memleaf-0.2.81}/src/memleaf/__init__.py

@@ -1,6 +1,6 @@
 """Local-first Markdown memory core for AI agents."""
 
-__version__ = "0.2.80"
+__version__ = "0.2.81"
 
 from .config import DEFAULT_CONFIG, default_config, load_config, save_config
 from .frontmatter import FrontmatterError, dump_frontmatter, dump_yaml, load_yaml, parse_frontmatter

{memleaf-0.2.80 → memleaf-0.2.81}/src/memleaf/cli.py

@@ -100,6 +100,13 @@ def build_parser() -> argparse.ArgumentParser:
                          help="allow remaining incremental transport recovery, not partial replan")
     process.add_argument("--dry-run", action="store_true", help="no source Vault writes; may call the configured model")
     process.add_argument("--json", action="store_true")
+    recovery = commands.add_parser("recover-run", help="preview or explicitly replan a failed automatic transport run")
+    recovery.add_argument("--vault", type=Path, default=None)
+    recovery.add_argument("--run-id", required=True)
+    recovery.add_argument("--apply", action="store_true", help="use the original remaining budget; requires preview revision")
+    recovery.add_argument("--expected-revision", default=None)
+    recovery.add_argument("--allow-legacy-http", action="store_true", help="explicitly retry one old HTTP failure whose status was not recorded")
+    recovery.add_argument("--json", action="store_true")
     maintenance = commands.add_parser("maintain-state", help="preview lossless terminal control-state compaction")
     maintenance.add_argument("--vault", type=Path, default=None)
     maintenance.add_argument("--apply", action="store_true", help="apply only to --expected-revision from preview")
@@ -274,6 +281,17 @@ def main(argv: Sequence[str] | None = None) -> int:
                 from .service import Memleaf
                 output = Memleaf(existing_root(args.vault)).process(
                     source=args.source, session_id=args.session_id, scope=args.scope, pipeline=args.pipeline, recover=args.recover)
+        elif args.command == "recover-run":
+            from .inspection import existing_root
+            from .service import Memleaf
+            from .incremental_failed_recovery import FailedRecoveryError
+            service = Memleaf(Vault(existing_root(args.vault), create=False))
+            try:
+                output = service.recover_failed_run(args.run_id, dry_run=not args.apply,
+                    expected_revision=args.expected_revision, allow_legacy_http=args.allow_legacy_http)
+            except FailedRecoveryError as error:
+                print(json.dumps({"run_id": args.run_id, "code": error.code, "status": "rejected"}))
+                return 1
         elif args.command == "maintain-state":
             from .inspection import existing_root
             from .service import Memleaf
@@ -318,15 +336,17 @@ def main(argv: Sequence[str] | None = None) -> int:
                 print("{}")
             return 0
         if getattr(args, "json", False):
-            print(json.dumps({"error": "operation failed" if args.command in {"audit", "process", "maintain-state", "migration-check", "migration-backup"}
+            print(json.dumps({"error": "operation failed" if args.command in {"audit", "process", "recover-run", "maintain-state", "migration-check", "migration-backup"}
                               else "initialization failed", "stage": args.command}, ensure_ascii=False))
         else:
             action = getattr(args, "command", "init")
             print(f"memleaf {action} failed unexpectedly", file=sys.stderr)
         return 1
 
-    if args.command in {"audit", "process", "maintain-state", "migration-check", "migration-backup"}:
+    if args.command in {"audit", "process", "recover-run", "maintain-state", "migration-check", "migration-backup"}:
         print(json.dumps(output, ensure_ascii=False, sort_keys=True, indent=None if args.json else 2))
+        if args.command == "recover-run":
+            return 2 if output.get("recoverable") is False or output.get("execution_status") in {"failed", "blocked", "cancelled"} else 0
         return 2 if args.command == "migration-check" and output["local_status"] != "clear" else 0
     if args.command == "host-event":
         print(json.dumps(output, ensure_ascii=False, separators=(",", ":")))

{memleaf-0.2.80 → memleaf-0.2.81}/src/memleaf/hermes_provider/plugin.yaml

@@ -1,5 +1,5 @@
 name: memleaf
-version: 0.2.80
+version: 0.2.81
 description: "Hermes-native external MemoryProvider for local-first Markdown memory shared with the memleaf MCP server."
 hooks:
   - prefetch

{memleaf-0.2.80 → memleaf-0.2.81}/src/memleaf/incremental_execution.py

@@ -28,7 +28,7 @@ from .incremental_run_state import (
 )
 from .index import turn_key
 from .inbox import captured_turn_selector
-from .llm.base import ModelError
+from .llm.base import ModelError, HTTP_RETRYABLE_STATUSES
 from .locking import atomic_write_json
 from .models import utc_now
 from .process_common import _read_processed
@@ -295,12 +295,14 @@ def _drive(service, run_id, token, backend, calls):
             if ordinal > 1 and not run.get("partial_used"):
                 request["system"] += RETRY_SYSTEM
         error_code = None
+        http_status = None
         response = None
         try:
             calls[0] += 1
             response = backend.complete(request["user"], system=request["system"], purpose="single_pass")
         except ModelError as error:
             error_code = error.code
+            http_status = error.http_status
         except Exception:
             error_code = "model_failed"  # Never persist provider exception text.
         with service.vault.lock():
@@ -309,7 +311,10 @@ def _drive(service, run_id, token, backend, calls):
                 return public_result(run, calls=calls[0])
             if error_code is not None:
                 run["attempts"][-1]["outcome"] = error_code
-                retryable = error_code in TRANSIENT and run["reserved_requests"] < 2
+                if http_status is not None:
+                    run["attempts"][-1]["http_status"] = http_status
+                retryable = (error_code in TRANSIENT or
+                             (error_code == "model_http_error" and http_status in HTTP_RETRYABLE_STATUSES)) and run["reserved_requests"] < 2
                 _finish(service, processed, run, "retryable" if retryable else "failed", error_code)
                 return public_result(run, calls=calls[0])
             if not isinstance(response, str) or not response.strip() or len(response.encode("utf-8")) > MAX_BYTES:

memleaf-0.2.81/src/memleaf/incremental_failed_recovery.py

@@ -0,0 +1,184 @@
+"""Explicit, revision-bound recovery of failed automatic transport runs.
+
+Preview never opens a Vault lock, calls a model or reconstructs persisted
+requests. Apply rebuilds a current request for unchanged source under the same
+run and budget, retaining the original failed attempt and a bounded audit.
+"""
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+from .extraction_work_state import _read_budget_state_unlocked, ExtractionWorkStateError
+from .incremental_commit import _window
+from .incremental_execution import (TRANSIENT, RETRY_SYSTEM, _guard_legacy, _protocol_digest,
+                                    resume_incremental_run)
+from .incremental_journal import digest, load_work
+from .incremental_preview import _prepare_incremental_unlocked
+from .incremental_prompts import INCREMENTAL_SYSTEM
+from .incremental_protocol import MAX_BYTES
+from .incremental_run_state import TERMINAL, MAX_RUNS, COMPACT_VERSION, load_run, owner_live, public_result, save_run
+from .llm.base import HTTP_RETRYABLE_STATUSES
+from .models import utc_now
+from .process_common import _read_processed
+from .recording_policy import recording_allowed
+from .turn_plan import input_digest, turn_identity_key
+from .receipt_codec import is_compact, ledger_usage
+
+
+class FailedRecoveryError(ValueError):
+    """Bounded public rejection, without private provider/source text."""
+
+    def __init__(self, code: str):
+        super().__init__(code)
+        self.code = code
+
+
+def _reject(code: str):
+    raise FailedRecoveryError(code)
+
+
+def _plan(service: Any, run_id: str, *, allow_legacy_http: bool):
+    processed = _read_processed(service.vault.processed_state_path)
+    run = load_run(processed, run_id)
+    if run is None:
+        _reject('incremental_run_not_found')
+    if (is_compact(processed['incremental_runs'][run_id], COMPACT_VERSION)
+            and ledger_usage(processed['incremental_runs'], compact_version=COMPACT_VERSION)['full'] >= MAX_RUNS):
+        _reject('active_run_capacity_unavailable')
+    if turn_identity_key(run['source'], run['session_id'], run['turn_key']) in processed.get('pending_turn_plans', {}):
+        _reject('legacy_pending_plan')
+    if run['status'] != 'failed' or 'terminal_recovery' in run:
+        _reject('terminal_recovery_not_available')
+    if run.get('request_kind', 'automatic') != 'automatic' or run['arguments'].get('selection'):
+        _reject('explicit_retention_requires_new_authorization')
+    if owner_live(processed):
+        _reject('incremental_model_busy')
+    _guard_legacy(service, processed)
+    attempts = run['attempts']
+    # Only a known failed first transport dispatch. Unknown reservations,
+    # responses, partial commits and exhausted attempts cannot be reopened.
+    if (len(attempts) != 1 or attempts[0]['ordinal'] != 1
+            or attempts[0]['outcome'] != run.get('code')
+            or run['reserved_requests'] != 1 or run.get('partial_used')):
+        _reject('terminal_recovery_attempt_not_eligible')
+    code = run.get('code')
+    status = attempts[0].get('http_status')
+    legacy = code == 'model_http_error' and status is None
+    if code == 'model_http_error':
+        if legacy and not allow_legacy_http:
+            _reject('legacy_http_status_unknown')
+        if not legacy and status not in HTTP_RETRYABLE_STATUSES:
+            _reject('http_error_not_retryable')
+    elif code not in TRANSIENT:
+        _reject('failure_not_retryable')
+    if not recording_allowed(processed, run['source'], run['session_id'], run['turn_key']):
+        _reject('source_recording_revoked')
+    if run['commit_work_id'] in processed.get('incremental_commits', {}):
+        _reject('source_already_owned')
+    turn, window = _window(service, run['source'], run['session_id'], run['turn_key'])
+    if not turn.processable or input_digest(turn) != run['source_digest']:
+        _reject('source_changed')
+    from .extraction_work_state import extraction_work_id
+    if extraction_work_id(turn, request_kind='automatic', intent_id='automatic') != run['budget_id']:
+        _reject('source_budget_identity_changed')
+    session = processed.get('sessions', {}).get(f"{run['source']}/{run['session_id']}", {})
+    if any(isinstance(entry, dict) and entry.get('turn_key') == run['turn_key']
+           for entry in session.get('processed_turns', [])):
+        _reject('source_already_processed')
+    for key in processed.get('incremental_commits', {}):
+        work = load_work(processed, key)
+        if (work['source'] == run['source'] and work['session_id'] == run['session_id']
+                and work['turn_key'] == run['turn_key']
+                and work.get('request_kind', 'automatic') == 'automatic'):
+            _reject('source_already_owned')
+    for key in processed.get('incremental_runs', {}):
+        other = load_run(processed, key)
+        if (key != run_id and other['source'] == run['source']
+                and other['session_id'] == run['session_id'] and other['turn_key'] == run['turn_key']
+                and other['status'] not in TERMINAL):
+            _reject('source_already_owned')
+    try:
+        budget = _read_budget_state_unlocked(service.vault)
+    except ExtractionWorkStateError:
+        _reject('remaining_request_budget_unavailable')
+    work_budget = budget['works'].get(run['budget_id'], {})
+    row = work_budget.get('turns', {}).get(run['turn_budget_id'])
+    if (not row or work_budget.get('retired') or row['completed'] or run.get('budget_finalized')
+            or row['requests'] != 1 or row['request_limit_at_creation'] <= row['requests']):
+        _reject('remaining_request_budget_unavailable')
+    snapshot = _prepare_incremental_unlocked(service, **run['arguments'])
+    request = {'system': INCREMENTAL_SYSTEM,
+               'user': json.dumps(snapshot.model_input(), ensure_ascii=False, separators=(',', ':'))}
+    if sum(len(s.encode('utf-8')) for s in request.values()) + len(RETRY_SYSTEM.encode('utf-8')) > MAX_BYTES:
+        _reject('blocked_context')
+    # Preview has no advisory lock. Confirm the independently read planning
+    # state/budget stayed stable; apply repeats this inside the existing lock.
+    if (processed != _read_processed(service.vault.processed_state_path)
+            or budget != _read_budget_state_unlocked(service.vault)):
+        _reject('recovery_preview_changed')
+    revision = digest({'processed': processed, 'budget': budget, 'source_window': window,
+                       'snapshot': snapshot.snapshot_id, 'protocol': _protocol_digest(),
+                       'allow_legacy_http': allow_legacy_http, 'run_id': run_id})
+    result = {'run_id': run_id, 'recoverable': True, 'read_only': True, 'model_calls': 0,
+              'expected_revision': revision, 'remaining_requests': 1,
+              'http_status': status, 'legacy_http_status_unknown': legacy,
+              'source_unchanged': True, 'source_window_changed': window != run['source_window'],
+              'snapshot_changed': snapshot.snapshot_id != run['snapshot_id'],
+              'new_events': sum(e['use'] == 'new' for e in snapshot.state()['evidence']),
+              'context_events': sum(e['use'] == 'context' for e in snapshot.state()['evidence'])}
+    return processed, run, snapshot, window, request, result
+
+
+def recover_failed_run(service: Any, run_id: str, *, dry_run: bool = True,
+                       expected_revision: str | None = None, allow_legacy_http: bool = False,
+                       model: Any = None, router: Any = None) -> dict[str, Any]:
+    if type(dry_run) is not bool or type(allow_legacy_http) is not bool:
+        _reject('invalid_recovery_options')
+    if dry_run:
+        try:
+            return _plan(service, run_id, allow_legacy_http=allow_legacy_http)[-1]
+        except (ValueError, OSError, ExtractionWorkStateError) as error:
+            # Known local validators emit reason codes, never source bodies.
+            code = error.code if isinstance(error, FailedRecoveryError) else 'recovery_preflight_failed'
+            return {'run_id': run_id, 'recoverable': False, 'read_only': True,
+                    'model_calls': 0, 'code': code}
+    if not isinstance(expected_revision, str) or re.fullmatch(r'[0-9a-f]{64}', expected_revision) is None:
+        _reject('expected_recovery_revision_required')
+    from .incremental_runtime import _resolve
+    # A repeated apply is the same original run, not another authorization.
+    with service.vault.lock():
+        stored = load_run(_read_processed(service.vault.processed_state_path), run_id)
+        audit = stored.get('terminal_recovery') if stored else None
+        if audit is not None:
+            if audit['expected_revision'] != expected_revision or audit['allow_legacy_http'] != allow_legacy_http:
+                _reject('recovery_already_bound')
+            if stored['status'] in TERMINAL:
+                return public_result(stored)
+            # Active/resumable same-intent work uses the existing owner guard.
+            already_bound = True
+        else:
+            already_bound = False
+        if not already_bound:
+            processed, run, snapshot, window, request, preview = _plan(
+                service, run_id, allow_legacy_http=allow_legacy_http)
+            if preview['expected_revision'] != expected_revision:
+                _reject('stale_recovery_preview')
+            backend = _resolve(service, model, router)
+            audit = {'version': 1, 'expected_revision': expected_revision,
+                     'allow_legacy_http': allow_legacy_http, 'previous_code': run['code'],
+                     'previous_snapshot_id': run['snapshot_id'], 'previous_source_window': run['source_window'],
+                     'requested_at': utc_now()}
+            run.update(status='ready', code=None, snapshot_id=snapshot.snapshot_id, source_window=window,
+                       request=request, request_digest=digest(request), protocol_digest=_protocol_digest(),
+                       source_keys=[e['event_key'] for e in snapshot.state()['evidence']],
+                       target_ids=[t['memory']['memory_id'] for t in snapshot.state()['targets'].values()],
+                       terminal_recovery=audit)
+            save_run(service, processed, run)
+    if already_bound:
+        # Resolve only if a dispatch is still needed. Saved responses/commits
+        # remain recoverable with zero model calls and no API configuration.
+        backend = (_resolve(service, model, router) if stored['status'] in {'ready', 'retryable', 'dispatching'}
+                   else None)
+    return resume_incremental_run(service, run_id, backend=backend)

{memleaf-0.2.80 → memleaf-0.2.81}/src/memleaf/incremental_run_state.py

@@ -84,6 +84,20 @@ def load_run(processed: dict[str, Any], run_id: str) -> dict[str, Any] | None:
                 or not 1 <= attempt["ordinal"] <= 2 or attempt.get("outcome") not in
                 ("unknown", "response", "invalid_response", "model_timeout", "model_rate_limited", "model_network_error", "model_failed", "model_auth_failed", "model_unavailable", "model_http_error", "model_invalid_response")):
             raise ValueError("invalid_incremental_attempt")
+        if "http_status" in attempt and (type(attempt["http_status"]) is not int or not 100 <= attempt["http_status"] <= 599):
+            raise ValueError("invalid_incremental_http_status")
+    audit = run.get("terminal_recovery")
+    if audit is not None:
+        required = {"version", "expected_revision", "allow_legacy_http", "previous_code",
+                    "previous_snapshot_id", "previous_source_window", "requested_at"}
+        if (not isinstance(audit, dict) or set(audit) != required or type(audit.get("version")) is not int
+                or audit["version"] != 1 or type(audit.get("allow_legacy_http")) is not bool
+                or audit.get("previous_code") not in {"model_http_error", "model_timeout", "model_rate_limited", "model_network_error", "model_invalid_response"}
+                or any(not isinstance(audit.get(k), str) or re.fullmatch(r"[0-9a-f]{64}", audit[k]) is None
+                       for k in ("expected_revision", "previous_snapshot_id", "previous_source_window"))
+                or not isinstance(audit.get("requested_at"), str) or not audit["requested_at"]
+                or kind != "automatic" or not run["attempts"] or run["attempts"][0]["outcome"] != audit["previous_code"]):
+            raise ValueError("invalid_terminal_recovery")
     if run["status"] not in TERMINAL:
         request = run.get("request")
         if (not isinstance(request, dict) or set(request) != {"system", "user"}
@@ -115,7 +129,7 @@ def save_run(service: Any, processed: dict[str, Any], run: dict[str, Any]) -> No
         raise ValueError("incremental_runs_full")
     runs[run["run_id"]] = {"version": VERSION, "payload": payload,
                            "checksum": hashlib.sha256(payload.encode("utf-8")).hexdigest()}
-    if is_compact(previous, COMPACT_VERSION):
+    if is_compact(previous, COMPACT_VERSION) and run["status"] in TERMINAL:
         runs[run["run_id"]] = encode_receipt(runs[run["run_id"]], version=COMPACT_VERSION)
     ledger_usage(runs, compact_version=COMPACT_VERSION)
     if len(canonical(runs).encode("utf-8")) > MAX_LEDGER_BYTES:
@@ -184,6 +198,9 @@ def public_result(run: dict[str, Any], *, calls: int = 0) -> dict[str, Any]:
         "request_kind": run.get("request_kind", "automatic"),
         **({"intent_id": run["authorization_intent"]} if "authorization_intent" in run else {}),
         "code": run.get("code"), "commit_work_id": run["commit_work_id"],
+        **({"http_status": run["attempts"][-1]["http_status"]} if run["attempts"] and "http_status" in run["attempts"][-1] else {}),
+        **({"terminal_recovery": {"expected_revision": run["terminal_recovery"]["expected_revision"],
+                                  "previous_code": run["terminal_recovery"]["previous_code"]}} if "terminal_recovery" in run else {}),
         "model_calls_this_invocation": calls,
         "model_calls_known": sum(a["outcome"] != "unknown" for a in run["attempts"]),
         "reserved_requests": run["reserved_requests"], "request_limit": 2,

{memleaf-0.2.80 → memleaf-0.2.81}/src/memleaf/llm/base.py

@@ -28,6 +28,7 @@ MODEL_ERROR_CODES = frozenset(
     }
 )
 MODEL_ERROR_STAGES = frozenset({"gate", "summarize", "single_pass"})
+HTTP_RETRYABLE_STATUSES = frozenset({408, 500, 502, 503, 504})
 MODEL_VALIDATION_REASONS = frozenset(
     {"empty_content", "invalid_json", "schema_violation", "response_shape"}
 )
@@ -92,6 +93,7 @@ class ModelError(RuntimeError):
         code: str = "model_failed",
         stage: str | None = None,
         validation_reason: str | None = None,
+        http_status: int | None = None,
     ):
         # Existing callers may still provide a descriptive local message.  The
         # public MCP/marker paths use only ``code`` and ``stage``.
@@ -99,6 +101,9 @@ class ModelError(RuntimeError):
         self.code = _safe_error_code(code)
         self.stage = _safe_error_stage(stage)
         self.validation_reason = _safe_validation_reason(validation_reason)
+        # Status alone is safe to retain; never retain the provider response,
+        # URL, headers or free-form HTTP reason in a diagnostic receipt.
+        self.http_status = http_status if type(http_status) is int and 100 <= http_status <= 599 else None
         self.response_diagnostics: dict[str, Any] = {}
 
     def with_stage(self, stage: str | None) -> "ModelError":
@@ -322,6 +327,7 @@ class HTTPModelBackend:
                     close()
         except urllib.error.HTTPError as error:
             status = getattr(error, "code", None)
+            status = status if type(status) is int and 100 <= status <= 599 else None
             if status in (401, 403):
                 code = "model_auth_failed"
                 message = "model authentication failed"
@@ -335,7 +341,7 @@ class HTTPModelBackend:
                 error.close()
             except Exception:
                 pass
-            raise ModelError(message, code=code, stage=stage) from None
+            raise ModelError(message, code=code, stage=stage, http_status=status) from None
         except TimeoutError:
             raise ModelError("model request timed out", code="model_timeout", stage=stage) from None
         except urllib.error.URLError as error:

{memleaf-0.2.80 → memleaf-0.2.81}/src/memleaf/mcp_server.py

@@ -318,6 +318,18 @@ _TOOLS: tuple[dict[str, Any], ...] = (
             }
         ),
     },
+    {
+        "name": "recover_failed_run",
+        "description": (
+            "Preview a failed automatic transport run without writes or model calls. "
+            "Only an explicit recovery request may set apply=true with the exact preview expected_revision. "
+            "Preserves original request budget; allow_legacy_http explicitly acknowledges an unrecorded old HTTP status."
+        ),
+        "inputSchema": _object_schema({
+            "run_id": {"type": "string"}, "apply": {"type": "boolean"},
+            "expected_revision": {"type": "string"}, "allow_legacy_http": {"type": "boolean"},
+        }, required=["run_id"]),
+    },
     {
         "name": "process_status",
         "description": (
@@ -744,6 +756,9 @@ def _safe_model_diagnostics(error: BaseException, *, default_reason: str | None
     if not isinstance(detail, str) or detail not in MODEL_VALIDATION_DETAILS:
         detail = "other_schema_violation" if isinstance(error, ModelOutputError) else None
     fields: dict[str, Any] = {}
+    http_status = getattr(error, "http_status", None)
+    if type(http_status) is int and 100 <= http_status <= 599:
+        fields["http_status"] = http_status
     if reason is not None:
         fields["validation_reason"] = reason
     if detail is not None:
@@ -754,6 +769,9 @@ def _safe_model_diagnostics(error: BaseException, *, default_reason: str | None
 
 
 def _tool_error(error: BaseException) -> dict[str, Any]:
+    from .incremental_failed_recovery import FailedRecoveryError
+    if isinstance(error, FailedRecoveryError):
+        return _tool_result({"status": "error", "error": {"code": error.code, "message": "failed run recovery rejected"}}, is_error=True)
     if isinstance(error, (RetrievalError, RetrievalGateError)):
         return _tool_result(
             {"status": "error", "error": {"code": error.code, "message": str(error)}},
@@ -1070,6 +1088,9 @@ def _invoke_tool(
                     value = HostRuntime(service, source).process(**args)
                 else:
                     value = service.process(**args)
+        elif name == "recover_failed_run":
+            value = service.recover_failed_run(args["run_id"], dry_run=not args.get("apply", False),
+                expected_revision=args.get("expected_revision"), allow_legacy_http=args.get("allow_legacy_http", False))
         elif name == "process_status":
             job_id = args.get("job_id")
             if isinstance(job_id, str) and job_id:

{memleaf-0.2.80 → memleaf-0.2.81}/src/memleaf/processing_route.py

@@ -151,6 +151,7 @@ def _row(turn, result):
             "turn_index": turn.turn_index, "run_id": result.get("run_id"),
             "work_id": result.get("commit_work_id"), "execution_status": result["execution_status"],
             "code": result.get("code"), "memory_ids": ids,
+            **({"http_status": result["http_status"]} if "http_status" in result else {}),
             "model_calls": result.get("model_calls_this_invocation", 0),
             "reservations": result.get("reserved_requests", 0),
             "unresolved_evidence_count": len(unresolved_refs),
@@ -325,7 +326,8 @@ def health_view(vault) -> dict[str, Any]:
     pending_commits = sum(commit_result(work)["execution_status"] == "recovery_required" for work in works)
     details = [{"run_id": run["run_id"], "source": run["source"], "session_id": run["session_id"],
                 "execution_status": run["status"], "code": run.get("code"),
-                "reserved_requests": run["reserved_requests"]}
+                "reserved_requests": run["reserved_requests"],
+                **({"http_status": run["attempts"][-1]["http_status"]} if run["attempts"] and "http_status" in run["attempts"][-1] else {})}
                for run in runs if run["status"] != "completed"]
     live = owner_live(state)
     from .query_progress import retention_inventory

{memleaf-0.2.80 → memleaf-0.2.81}/src/memleaf/service.py

@@ -460,6 +460,14 @@ class Memleaf:
                                            context_memory_ids=context_memory_ids,
                                            model=model, router=router)
 
+    def recover_failed_run(self, run_id: str, *, dry_run: bool = True,
+                           expected_revision: str | None = None, allow_legacy_http: bool = False,
+                           model: Any = None, router: Any = None) -> dict[str, Any]:
+        """Preview/apply explicit terminal transport recovery using original budget."""
+        from .incremental_failed_recovery import recover_failed_run
+        return recover_failed_run(self, run_id, dry_run=dry_run, expected_revision=expected_revision,
+                                  allow_legacy_http=allow_legacy_http, model=model, router=router)
+
     def resume_incremental_run(self, run_id: str, *, backend: Any = None) -> dict[str, Any]:
         """Resume a frozen response/commit without another model request when possible."""
         from .incremental_execution import resume_incremental_run