omnius 1.0.700 → 1.0.701

package/dist/library.js

@@ -247454,6 +247454,145 @@ init_process_lifecycle();
 // packages/execution/dist/tools/desktop-control.js
 init_system_deps();
 
+// packages/execution/dist/tools/archive-extract.js
+init_process_async();
+var EXTRACT = String.raw`
+import json, os, re, stat, sys, tarfile, zipfile
+source, stage = sys.argv[1:3]
+limits = json.loads(sys.argv[3])
+seen, kinds, preview = set(), {}, []
+entries = files = total = 0
+root = os.open(stage, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+
+def path_parts(name, kind):
+    if not isinstance(name, str) or not name or '\x00' in name or '\\' in name or name.startswith('/') or re.match(r'^[a-zA-Z]:', name):
+        raise ValueError('unsafe absolute or invalid archive path')
+    raw = name.split('/')
+    if '..' in raw:
+        raise ValueError('archive path traversal rejected')
+    parts = [part for part in raw if part not in ('', '.')]
+    key = '/'.join(parts)
+    if not parts and kind != 'directory':
+        raise ValueError('invalid empty file path')
+    if key in seen:
+        raise ValueError('duplicate archive path rejected')
+    seen.add(key)
+    for index in range(1, len(parts)):
+        parent = '/'.join(parts[:index])
+        if kinds.get(parent) == 'file':
+            raise ValueError('archive file/directory collision rejected')
+        kinds[parent] = 'directory'
+    if key in kinds and (kind != 'directory' or kinds[key] != 'directory'):
+        raise ValueError('archive path collision rejected')
+    if key:
+        kinds[key] = kind
+    return parts
+
+def parent_fd(parts):
+    fd = os.dup(root)
+    try:
+        for part in parts:
+            try:
+                os.mkdir(part, 0o700, dir_fd=fd)
+            except FileExistsError:
+                pass
+            child = os.open(part, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=fd)
+            os.close(fd)
+            fd = child
+        return fd
+    except BaseException:
+        os.close(fd)
+        raise
+
+def member(name, kind, declared, opener):
+    global entries, files, total
+    entries += 1
+    if limits.get('maxEntries') is not None and entries > limits['maxEntries']:
+        raise ValueError('explicit maxEntries limit exceeded')
+    parts = path_parts(name, kind)
+    if kind == 'directory':
+        fd = parent_fd(parts)
+        os.close(fd)
+    else:
+        if declared < 0:
+            raise ValueError('invalid archive file size')
+        if limits.get('maxOutputBytes') is not None and total + declared > limits['maxOutputBytes']:
+            raise ValueError('explicit maxOutputBytes limit exceeded')
+        fd = parent_fd(parts[:-1])
+        try:
+            output = os.open(parts[-1], os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600, dir_fd=fd)
+        finally:
+            os.close(fd)
+        written = 0
+        with os.fdopen(output, 'wb') as target, opener() as input_file:
+            while True:
+                chunk = input_file.read(1024 * 1024)
+                if not chunk:
+                    break
+                if limits.get('maxOutputBytes') is not None and total + len(chunk) > limits['maxOutputBytes']:
+                    raise ValueError('explicit maxOutputBytes limit exceeded')
+                target.write(chunk)
+                written += len(chunk)
+                total += len(chunk)
+        if written != declared:
+            raise ValueError('archive member length mismatch')
+        files += 1
+    if len(preview) < 40:
+        preview.append({'path': '/'.join(parts)[:512], 'kind': kind, 'bytes': declared if kind == 'file' else 0})
+
+try:
+    if zipfile.is_zipfile(source):
+        archive_format = 'zip'
+        with zipfile.ZipFile(source) as archive:
+            for info in archive.infolist():
+                mode = stat.S_IFMT(info.external_attr >> 16)
+                if mode not in (0, stat.S_IFREG, stat.S_IFDIR):
+                    raise ValueError('archive links, devices and special entries are not allowed')
+                kind = 'directory' if info.is_dir() or mode == stat.S_IFDIR else 'file'
+                member(info.orig_filename, kind, info.file_size, lambda info=info: archive.open(info, 'r'))
+    else:
+        archive_format = 'tar'
+        with tarfile.open(source, 'r|*') as archive:
+            for info in archive:
+                if not (info.isdir() or info.isreg()):
+                    raise ValueError('archive links, devices and special entries are not allowed')
+                member(info.name, 'directory' if info.isdir() else 'file', info.size, lambda info=info: archive.extractfile(info))
+    print(json.dumps({'format': archive_format, 'entries': entries, 'files': files,
+        'directories': sum(kind == 'directory' for kind in kinds.values()), 'bytes': total,
+        'preview': preview, 'previewOmitted': max(0, entries - len(preview))}))
+except BaseException as error:
+    # Exception messages from standard readers can contain untrusted filenames;
+    # report a bounded JSON string, never executable or control-sequence output.
+    print(json.dumps({'error': str(error)[:600]}), file=sys.stderr)
+    sys.exit(1)
+finally:
+    os.close(root)
+`;
+var PUBLISH = String.raw`
+import ctypes, errno, json, os, stat, sys
+parent, stage, target, dev, ino = sys.argv[1:]
+try:
+    fd = os.open(parent, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+    entry = os.stat(stage, dir_fd=fd, follow_symlinks=False)
+    if not stat.S_ISDIR(entry.st_mode) or entry.st_dev != int(dev) or entry.st_ino != int(ino):
+        raise ValueError('staging ownership changed before publication')
+    libc = ctypes.CDLL(None, use_errno=True)
+    rename = getattr(libc, 'renameat2', None)
+    if rename is None:
+        raise ValueError('atomic no-replace directory publication is unavailable on this platform')
+    rename.argtypes = [ctypes.c_int, ctypes.c_char_p, ctypes.c_int, ctypes.c_char_p, ctypes.c_uint]
+    rename.restype = ctypes.c_int
+    if rename(fd, os.fsencode(stage), fd, os.fsencode(target), 1) != 0:
+        code = ctypes.get_errno()
+        if code == errno.EEXIST:
+            raise ValueError('destination already exists; nothing was overwritten')
+        raise OSError(code, os.strerror(code))
+    os.close(fd)
+except BaseException as error:
+    print(json.dumps({'error': str(error)[:600]}), file=sys.stderr)
+    sys.exit(1)
+`;
+
 // packages/execution/dist/tools/change-log.js
 import { randomBytes } from "node:crypto";
 var _sessionId = `session-${Date.now()}-${randomBytes(3).toString("hex")}`;

package/dist/update-worker.js

@@ -245166,6 +245166,145 @@ init_process_lifecycle();
 // packages/execution/dist/tools/desktop-control.js
 init_system_deps();
 
+// packages/execution/dist/tools/archive-extract.js
+init_process_async();
+var EXTRACT = String.raw`
+import json, os, re, stat, sys, tarfile, zipfile
+source, stage = sys.argv[1:3]
+limits = json.loads(sys.argv[3])
+seen, kinds, preview = set(), {}, []
+entries = files = total = 0
+root = os.open(stage, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+
+def path_parts(name, kind):
+    if not isinstance(name, str) or not name or '\x00' in name or '\\' in name or name.startswith('/') or re.match(r'^[a-zA-Z]:', name):
+        raise ValueError('unsafe absolute or invalid archive path')
+    raw = name.split('/')
+    if '..' in raw:
+        raise ValueError('archive path traversal rejected')
+    parts = [part for part in raw if part not in ('', '.')]
+    key = '/'.join(parts)
+    if not parts and kind != 'directory':
+        raise ValueError('invalid empty file path')
+    if key in seen:
+        raise ValueError('duplicate archive path rejected')
+    seen.add(key)
+    for index in range(1, len(parts)):
+        parent = '/'.join(parts[:index])
+        if kinds.get(parent) == 'file':
+            raise ValueError('archive file/directory collision rejected')
+        kinds[parent] = 'directory'
+    if key in kinds and (kind != 'directory' or kinds[key] != 'directory'):
+        raise ValueError('archive path collision rejected')
+    if key:
+        kinds[key] = kind
+    return parts
+
+def parent_fd(parts):
+    fd = os.dup(root)
+    try:
+        for part in parts:
+            try:
+                os.mkdir(part, 0o700, dir_fd=fd)
+            except FileExistsError:
+                pass
+            child = os.open(part, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=fd)
+            os.close(fd)
+            fd = child
+        return fd
+    except BaseException:
+        os.close(fd)
+        raise
+
+def member(name, kind, declared, opener):
+    global entries, files, total
+    entries += 1
+    if limits.get('maxEntries') is not None and entries > limits['maxEntries']:
+        raise ValueError('explicit maxEntries limit exceeded')
+    parts = path_parts(name, kind)
+    if kind == 'directory':
+        fd = parent_fd(parts)
+        os.close(fd)
+    else:
+        if declared < 0:
+            raise ValueError('invalid archive file size')
+        if limits.get('maxOutputBytes') is not None and total + declared > limits['maxOutputBytes']:
+            raise ValueError('explicit maxOutputBytes limit exceeded')
+        fd = parent_fd(parts[:-1])
+        try:
+            output = os.open(parts[-1], os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600, dir_fd=fd)
+        finally:
+            os.close(fd)
+        written = 0
+        with os.fdopen(output, 'wb') as target, opener() as input_file:
+            while True:
+                chunk = input_file.read(1024 * 1024)
+                if not chunk:
+                    break
+                if limits.get('maxOutputBytes') is not None and total + len(chunk) > limits['maxOutputBytes']:
+                    raise ValueError('explicit maxOutputBytes limit exceeded')
+                target.write(chunk)
+                written += len(chunk)
+                total += len(chunk)
+        if written != declared:
+            raise ValueError('archive member length mismatch')
+        files += 1
+    if len(preview) < 40:
+        preview.append({'path': '/'.join(parts)[:512], 'kind': kind, 'bytes': declared if kind == 'file' else 0})
+
+try:
+    if zipfile.is_zipfile(source):
+        archive_format = 'zip'
+        with zipfile.ZipFile(source) as archive:
+            for info in archive.infolist():
+                mode = stat.S_IFMT(info.external_attr >> 16)
+                if mode not in (0, stat.S_IFREG, stat.S_IFDIR):
+                    raise ValueError('archive links, devices and special entries are not allowed')
+                kind = 'directory' if info.is_dir() or mode == stat.S_IFDIR else 'file'
+                member(info.orig_filename, kind, info.file_size, lambda info=info: archive.open(info, 'r'))
+    else:
+        archive_format = 'tar'
+        with tarfile.open(source, 'r|*') as archive:
+            for info in archive:
+                if not (info.isdir() or info.isreg()):
+                    raise ValueError('archive links, devices and special entries are not allowed')
+                member(info.name, 'directory' if info.isdir() else 'file', info.size, lambda info=info: archive.extractfile(info))
+    print(json.dumps({'format': archive_format, 'entries': entries, 'files': files,
+        'directories': sum(kind == 'directory' for kind in kinds.values()), 'bytes': total,
+        'preview': preview, 'previewOmitted': max(0, entries - len(preview))}))
+except BaseException as error:
+    # Exception messages from standard readers can contain untrusted filenames;
+    # report a bounded JSON string, never executable or control-sequence output.
+    print(json.dumps({'error': str(error)[:600]}), file=sys.stderr)
+    sys.exit(1)
+finally:
+    os.close(root)
+`;
+var PUBLISH = String.raw`
+import ctypes, errno, json, os, stat, sys
+parent, stage, target, dev, ino = sys.argv[1:]
+try:
+    fd = os.open(parent, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+    entry = os.stat(stage, dir_fd=fd, follow_symlinks=False)
+    if not stat.S_ISDIR(entry.st_mode) or entry.st_dev != int(dev) or entry.st_ino != int(ino):
+        raise ValueError('staging ownership changed before publication')
+    libc = ctypes.CDLL(None, use_errno=True)
+    rename = getattr(libc, 'renameat2', None)
+    if rename is None:
+        raise ValueError('atomic no-replace directory publication is unavailable on this platform')
+    rename.argtypes = [ctypes.c_int, ctypes.c_char_p, ctypes.c_int, ctypes.c_char_p, ctypes.c_uint]
+    rename.restype = ctypes.c_int
+    if rename(fd, os.fsencode(stage), fd, os.fsencode(target), 1) != 0:
+        code = ctypes.get_errno()
+        if code == errno.EEXIST:
+            raise ValueError('destination already exists; nothing was overwritten')
+        raise OSError(code, os.strerror(code))
+    os.close(fd)
+except BaseException as error:
+    print(json.dumps({'error': str(error)[:600]}), file=sys.stderr)
+    sys.exit(1)
+`;
+
 // packages/execution/dist/tools/change-log.js
 import { randomBytes } from "node:crypto";
 var _sessionId = `session-${Date.now()}-${randomBytes(3).toString("hex")}`;

package/docs/DISCOVERY.json

@@ -31584,6 +31584,38 @@
         }
       ]
     },
+    {
+      "id": "guide.telegram-large-files",
+      "kind": "guide",
+      "title": "Receiving large Telegram files",
+      "summary": "Omnius has no default inbound attachment byte cap or cache byte cap. Downloads stream to disk, retaining only a small signature prefix in memory. Cache item-count and age eviction still apply. Authenticated admin DMs can pass an uploaded document's exact Telegram alias to fileread or archiveextract; extraction returns a destination and file manifest for subs",
+      "keywords": [
+        "telegram",
+        "large",
+        "files",
+        "md"
+      ],
+      "maturity": "stable",
+      "audiences": [
+        "user",
+        "integrator",
+        "coding-agent"
+      ],
+      "layer": "documentation",
+      "interfaces": [
+        {
+          "type": "file",
+          "target": "docs/telegram-large-files.md"
+        }
+      ],
+      "references": [
+        {
+          "type": "documentation",
+          "target": "docs/telegram-large-files.md",
+          "relation": "canonical-artifact"
+        }
+      ]
+    },
     {
       "id": "guide.telegram-mid-horizon-download-loop-handoff",
       "kind": "guide",
@@ -35244,6 +35276,82 @@
         }
       ]
     },
+    {
+      "id": "guide.work-orders-runtime-health-remediation-wo-51-large-telegram-attachments-uppercase",
+      "kind": "guide",
+      "title": "WO-51: Receive and unpack large Telegram attachments",
+      "summary": "Status: source repair complete and verified. Publication and Local Bot API live acceptance remain with the operator.",
+      "keywords": [
+        "work",
+        "orders",
+        "runtime",
+        "health",
+        "remediation",
+        "WO",
+        "51",
+        "large",
+        "telegram",
+        "attachments",
+        "md"
+      ],
+      "maturity": "internal",
+      "audiences": [
+        "maintainer",
+        "large-context-agent"
+      ],
+      "layer": "documentation",
+      "interfaces": [
+        {
+          "type": "file",
+          "target": "docs/work-orders/runtime-health-remediation/WO-51-large-telegram-attachments.md"
+        }
+      ],
+      "references": [
+        {
+          "type": "documentation",
+          "target": "docs/work-orders/runtime-health-remediation/WO-51-large-telegram-attachments.md",
+          "relation": "canonical-artifact"
+        }
+      ]
+    },
+    {
+      "id": "guide.work-orders-runtime-health-remediation-wo-52-steering-projection-preservation-uppercase",
+      "kind": "guide",
+      "title": "WO-52: Preserve required steering instructions in the actual model request",
+      "summary": "Status: source repair complete; verified and ready for publication. Live acceptance follows the user's publication.",
+      "keywords": [
+        "work",
+        "orders",
+        "runtime",
+        "health",
+        "remediation",
+        "WO",
+        "52",
+        "steering",
+        "projection",
+        "preservation",
+        "md"
+      ],
+      "maturity": "internal",
+      "audiences": [
+        "maintainer",
+        "large-context-agent"
+      ],
+      "layer": "documentation",
+      "interfaces": [
+        {
+          "type": "file",
+          "target": "docs/work-orders/runtime-health-remediation/WO-52-steering-projection-preservation.md"
+        }
+      ],
+      "references": [
+        {
+          "type": "documentation",
+          "target": "docs/work-orders/runtime-health-remediation/WO-52-steering-projection-preservation.md",
+          "relation": "canonical-artifact"
+        }
+      ]
+    },
     {
       "id": "guide.work-orders-telegram-dmn-wo-22-dmn-outreach-and-learning-uppercase",
       "kind": "guide",
@@ -39664,6 +39772,62 @@
         }
       ]
     },
+    {
+      "id": "tool.archive-extract",
+      "kind": "tool",
+      "title": "Archive Extract",
+      "summary": "archive_extract is a directly callable Omnius tool.",
+      "aliases": [
+        "archive_extract"
+      ],
+      "keywords": [
+        "tool",
+        "archive",
+        "extract"
+      ],
+      "maturity": "stable",
+      "layer": "execution",
+      "audiences": [
+        "coding-agent",
+        "integrator",
+        "service-agent"
+      ],
+      "use_when": [
+        "The caller needs this isolated operation and live metadata confirms direct-call availability"
+      ],
+      "avoid_when": [
+        "The live registry reports the tool unavailable or the caller lacks its required scope"
+      ],
+      "interfaces": [
+        {
+          "type": "rest-schema",
+          "target": "/v1/tools/archive_extract"
+        },
+        {
+          "type": "rest-call",
+          "target": "/v1/tools/archive_extract/call"
+        }
+      ],
+      "references": [
+        {
+          "type": "source",
+          "target": "packages/execution/src/tools/archive-extract.ts",
+          "relation": "implementation"
+        }
+      ],
+      "direct_callable": true,
+      "live_metadata": "GET /v1/tools/archive_extract",
+      "source_of_truth": [
+        "packages/execution/src/tools/archive-extract.ts",
+        "GET /v1/tools/archive_extract"
+      ],
+      "verification": [
+        {
+          "check": "Inspect GET /v1/tools/archive_extract before use",
+          "expected": "Schema, security, exposure, and availability match the intended invocation"
+        }
+      ]
+    },
     {
       "id": "tool.asr-listen",
       "kind": "tool",

package/docs/DISCOVERY.md

@@ -499,6 +499,7 @@ Daemon equivalents are `GET /v1/discovery/bootstrap`, `GET /v1/discovery?q=<inte
 | `guide.sana-and-video-generation-integration-plan` | Sana (Image) + `/video` (Video Generation) Integration Plan | &gt; Status: Plan only. Builds a complete, anchored handoff for a downstream implementation agent. &gt; Goal: (A) Promote NVIDIA Sana to the primary image-generation model for /image and the image-generation tool, (B) ship an entirely new /video pipeline modeled exactly on the existing /image and /sound-/music patterns, including its agent tool, Telegram public/pr |
 | `guide.session-diary-llm-training-analysis` | Session Diary: LLM Training Alignment Analysis | Is the session diary format what LLMs are trained on, such that it helps system handling? |
 | `guide.telegram-dmn-curiosity-outreach-scaffold` | Telegram DMN Curiosity Outreach Scaffold | This document tracks the root design for idle Telegram channel "daydream" behavior: private meta-analysis while a public group is idle, curiosity-driven exploration, scoped tool awareness, same-group follow-up planning, private DM follow-up planning, and persona document steering. It is intentionally a scaffold: artifacts describe possible actions and tool a |
+| `guide.telegram-large-files` | Receiving large Telegram files | Omnius has no default inbound attachment byte cap or cache byte cap. Downloads stream to disk, retaining only a small signature prefix in memory. Cache item-count and age eviction still apply. Authenticated admin DMs can pass an uploaded document's exact Telegram alias to fileread or archiveextract; extraction returns a destination and file manifest for subs |
 | `guide.telegram-mid-horizon-download-loop-handoff` | Telegram Mid-Horizon Download Loop Handoff | A Telegram admin-DM action run for "can you please get me the pdf for Snow Crash" burned 60+ turns trying Archive.org, browser clicks, repeated curl downloads, and third-party PDF mirrors. It eventually sent visible self-talk to Telegram: |
 | `guide.telegram-reflection-corpus-integration-plan` | Telegram Reflection Corpus Integration Plan | Status: planning and implementation tracker |
 | `guide.telegram-unified-tooling-architecture` | Telegram Unified Tooling Architecture | Goal: give Telegram-sourced agent runs one scoped telegram tool that covers Telegram Bot API operations behind explicit Omnius policy, Telegram bot rights, and admin-controlled toggles. This replaces the current drift where some Telegram powers exist as private helpers, some exist as TUI slash commands, and only telegramsendfile is model-facing. |
@@ -596,6 +597,8 @@ Daemon equivalents are `GET /v1/discovery/bootstrap`, `GET /v1/discovery?q=<inte
 | `guide.work-orders-runtime-health-remediation-wo-48-conversation-result-evidence-uppercase` | WO-48: Retain command evidence in conversation results | Status: repository repair complete and delivered to origin/main. Publication and live validation remain with the user. |
 | `guide.work-orders-runtime-health-remediation-wo-49-authored-final-delivery-uppercase` | WO-49: Preserve the authored answer after tool work | Status: repository repair complete; delivered as bfaabd7f to origin/main. Publication and live acceptance remain with the user. |
 | `guide.work-orders-runtime-health-remediation-wo-50-embedding-unavailability-uppercase` | WO-50: Recover honestly from missing embeddings | Status: repository repair complete; delivered as a3375c63 to origin/main. Requested Nomic re-pull completed and passive server recovery observed. Publication and live acceptance of source changes remain with the user. |
+| `guide.work-orders-runtime-health-remediation-wo-51-large-telegram-attachments-uppercase` | WO-51: Receive and unpack large Telegram attachments | Status: source repair complete and verified. Publication and Local Bot API live acceptance remain with the operator. |
+| `guide.work-orders-runtime-health-remediation-wo-52-steering-projection-preservation-uppercase` | WO-52: Preserve required steering instructions in the actual model request | Status: source repair complete; verified and ready for publication. Live acceptance follows the user's publication. |
 | `guide.work-orders-telegram-dmn-wo-22-dmn-outreach-and-learning-uppercase` | WO-22: DMN outreach, DM sharing, and outcome learning | On 2026-09-03 at 17:07 PDT the bot posted in the OMNIUS group without being addressed. The operator asked whether this was self-induced reflection. |
 | `guide.work-orders-telegram-dropbear-context-rca-workorder` | Telegram Dropbear Context Engineering RCA Work Order | Observed run: /home/roko/Documents/Projects/Adjacent/telegramtest/.omnius, run id 1782873796963-i5r7mv. |
 | `guide.work-orders-wo-am-gaps-uppercase` | Associative Memory Gap Work Orders | Generated: 2026-04-13 Source: Deep audit of multimodal associative memory systems Status: READY FOR IMPLEMENTATION |
@@ -732,6 +735,7 @@ Daemon equivalents are `GET /v1/discovery/bootstrap`, `GET /v1/discovery?q=<inte
 | `tool.aiwg-health` | Aiwg Health | aiwg_health is a directly callable Omnius tool. |
 | `tool.aiwg-setup` | Aiwg Setup | aiwg_setup is a directly callable Omnius tool. |
 | `tool.aiwg-workflow` | Aiwg Workflow | aiwg_workflow is a directly callable Omnius tool. |
+| `tool.archive-extract` | Archive Extract | archive_extract is a directly callable Omnius tool. |
 | `tool.asr-listen` | Asr Listen | asr_listen is a directly callable Omnius tool. |
 | `tool.audio-analyze` | Audio Analyze | audio_analyze is a directly callable Omnius tool. |
 | `tool.audio-capture` | Audio Capture | audio_capture is a directly callable Omnius tool. |

package/docs/telegram-large-files.md

@@ -0,0 +1,37 @@
+# Receiving large Telegram files
+
+Omnius has no default inbound attachment byte cap or cache byte cap. Downloads stream to disk, retaining only a small signature prefix in memory. Cache item-count and age eviction still apply. Authenticated admin DMs can pass an uploaded document's exact Telegram alias to `file_read` or `archive_extract`; extraction returns a destination and file manifest for subsequent inspection.
+
+Telegram's hosted Bot API limits downloads to 20 MB. A [Local Bot API server](https://core.telegram.org/bots/api#using-a-local-bot-api-server) supports larger downloads. Omnius must use that server for polling and all Bot API methods as well as file retrieval.
+
+## Configure the transport
+
+Run the official [Telegram Bot API server](https://github.com/tdlib/telegram-bot-api#usage) in `--local` mode using your own Telegram API application credentials. Use a private endpoint and a shared files directory readable by Omnius. The server's absolute `file_path` must resolve to the same file in Omnius's filesystem; container deployments need matching mount paths. The server directory must not include unrelated private files.
+
+Merge these fields into the project's `.omnius/settings.json` or global `~/.omnius/settings.json`, preserving existing settings:
+
+```json
+{
+  "telegramBotApiBaseUrl": "http://127.0.0.1:8082",
+  "telegramBotApiLocalFilesRoot": "/srv/telegram-bot-api"
+}
+```
+
+These are example values: use the running server's actual endpoint and directory. Port 8081 on the reviewed host belongs to IPFS. Environment variables override the settings:
+
+| Setting | Environment variable | Default |
+| --- | --- | --- |
+| `telegramBotApiBaseUrl` | `OMNIUS_TELEGRAM_BOT_API_BASE_URL` | `https://api.telegram.org` |
+| `telegramBotApiLocalFilesRoot` | `OMNIUS_TELEGRAM_BOT_API_LOCAL_FILES_ROOT` | No local filesystem access |
+| `telegramMaxAttachmentBytes` | `OMNIUS_TELEGRAM_MAX_ATTACHMENT_BYTES` | No byte cap |
+| `telegramFileDownloadTimeoutMs` | `OMNIUS_TELEGRAM_FILE_DOWNLOAD_TIMEOUT_MS` | 600000 ms |
+
+Leave the attachment limit absent for uncapped downloads. Explicit limits and timeouts must be positive integers. Increase the download timeout for slower transfers; it also applies to `getFile` while the local server obtains the file. Restart Omnius after changing transport settings. Inference endpoint settings are independent.
+
+Before switching a running bot, stop its old poller and follow Telegram's [migration procedure](https://github.com/tdlib/telegram-bot-api#moving-a-bot-to-a-local-server), including calling the hosted server's `logOut` method before using the local endpoint. Do not run cloud and local pollers concurrently. This is a live bot migration, not a consequence of installing the source repair.
+
+## Archive consumption and verification
+
+`archive_extract` supports ZIP and TAR, including gzip/bzip2/xz-compressed TAR. It requires Python 3 and Linux `renameat2` support. It writes into a fresh destination within the working directory, rejects unsafe paths, links and special files, and never overwrites an existing destination. It does not execute uploaded code. There is no default extracted-byte or entry-count cap; optional `maxOutputBytes`, `maxEntries` and `timeout` arguments are available. Archive extraction is available in authenticated admin DMs under the existing filesystem-tool policy.
+
+After publishing and migrating the bot, resend the project archive and ask Omnius to extract it and read its README. Confirm the received byte count, extraction destination/manifest, actual file read, and a delivered result. The repository regression uses a ZIP above 37 MiB through mocked Telegram download, actual cache, alias resolution, extraction and file read. That passing test does not establish live migration or delivery.

package/docs/work-orders/runtime-health-remediation/TRACKER.md

@@ -4,6 +4,13 @@
 **Checked-item rule:** code, focused tests, and named evidence must all exist
 **Last reconciled:** 2026-09-05
 
+## September 5 runtime 1.0.700 large attachment follow-up
+
+- [x] [WO-51: large Telegram attachments](WO-51-large-telegram-attachments.md): fixed inbound/cache byte caps removed; streamed download, Local Bot API transport, exact archive aliases and responsive durable Stop verified. Archive implementation `dec18c74` and CLI integration `40a76cea` delivered to `origin/main`.
+- [x] [WO-52: steering projection preservation](WO-52-steering-projection-preservation.md): `766b72f3` delivered to `origin/main`; 118 regression tests passed, typecheck and final orchestrator build passed. Current instructions survive conversation/task projection and visibility receipts match actual admitted request content.
+
+The reviewed run rejected a 37.8 MB archive and then looped because the compiler removed its required reconciliation instructions. Ollama was answering requests; no ongoing backend outage was established in the latest journal window. Final verification: clean workspace build and final rebuild passed, execution 1,852 passed / 3 existing skips, CLI full run 2,656 passed plus the final guest-isolation case passed in the focused run (2,657 distinct CLI cases), orchestrator 118 focused regressions passed. Telegram's hosted 20 MB download limit remains external; live larger-file reception requires a configured Local Bot API server and shared directory, documented in [the setup guide](../../telegram-large-files.md). User publication and live acceptance remain pending.
+
 ## September 5 runtime 1.0.698 delivery and Ollama follow-up
 
 - [x] [WO-49: authored final delivery](WO-49-authored-final-delivery.md): later authored replies survive earlier prose, tool work and summary-only completion. Commit `bfaabd7f` delivered to `origin/main`; 280 orchestrator and 58 CLI checks passed.

package/docs/work-orders/runtime-health-remediation/WO-51-large-telegram-attachments.md

@@ -0,0 +1,56 @@
+# WO-51: Receive and unpack large Telegram attachments
+
+Status: source repair complete and verified. Publication and Local Bot API live acceptance remain with the operator.
+
+## Finding and requested behavior
+
+On September 5, 2026, runtime 1.0.700 rejected `agent-services.tar.gz` (37,752,526 bytes) against a hardcoded 26,214,400-byte document cap. The user explicitly requested consuming/unpacking files larger than 25 MB and removing the hardcoded cap. Evidence: copied latest run and request projection under `/tmp/omnius-latest-run-20260905-1550/`, intake and conversation capture under `/tmp/omnius-latest-telegram-p7sd8ubn/`.
+
+Additional root defects: downloads accumulated the entire file in RAM; the cache could immediately evict a newly received file above its byte budget; archive extensions became `.bin`; received-document aliases had no general reader or archive extractor. Every Bot API and download URL was fixed to Telegram's hosted server.
+
+Review also reproduced a FIFO blocking the local-file reader before its regular-file check, and a configured timeout above Node's timer range silently becoming 1 ms. Both are repaired with nonblocking special-file rejection and timer-range validation. The inbound polling loop awaited eager media downloads before accepting subsequent controls; responsive durable dispatch and owned Stop cancellation are included in this order.
+
+## Repair and owned paths
+
+- `packages/cli/src/tui/telegram-media-admission.ts` and `platforms/attachment-store.ts`: no default inbound byte cap; explicit operator limits remain optional. Preserve valid file metadata and archive extensions.
+- `telegram-file-download.ts`: stream HTTP or shared local files into exclusive owned cache files; cancellation, partial-write cleanup, prefix-only signature inspection and optional configured limits.
+- `telegram-bot-transport.ts`, `omnius-directory.ts`, `telegram-bridge.ts`: one configured Bot API URL for polling, methods, uploads and downloads; trusted-root handling of local Bot API file paths; independent inference endpoint; no default cache byte eviction; exact chat/message aliases for admin document reads and extraction.
+- `packages/execution/src/tools/archive-extract.ts`: streamed ZIP/TAR extraction into a fresh owned directory, no default byte cap, no content execution, no overwrite, reject traversal/links/devices and report actual manifest facts. Optional explicit resource limits remain available.
+- CLI/execution tests: a real archive larger than 25 MiB through mocked Telegram transport, cache, extraction and file read; local paths; scope/cancellation/cleanup/error controls.
+- `tool-policy.ts` and execution `security-classifier.ts`: classify extraction as a local write and retain the existing admin-DM filesystem boundary, including when public allowlists are expanded.
+- Operator configuration and migration procedure: [Receiving large Telegram files](../../telegram-large-files.md).
+
+## Acceptance
+
+- [x] A 37 MiB attachment passes default admission and streamed cache storage without whole-file buffering.
+- [x] Files above former cache byte budgets remain available by exact message alias.
+- [x] Actual archive extraction and subsequent file read succeed; paths cannot escape the owned extraction destination or another chat's media scope.
+- [x] Configured local Bot API URLs and shared paths are respected throughout transport; cloud download refusal is actionable.
+- [x] Cancellation, existing destinations, malformed streams and unsafe archive entries fail honestly and preserve unrelated files.
+- [x] Polling and authorized Stop remain responsive during large-file transfers; cancelled work cannot start afterward.
+- [x] Record tests, builds, scoped commits and push.
+
+## Recorded verification
+
+- Execution: 1,852 passed / 3 existing skips across 164 suites, including 31 archive cases and the mutation-authority regression. Command: `pnpm --dir packages/execution exec vitest run --maxWorkers=4 --minWorkers=1`; log `/tmp/omnius-wo51-execution-full.log`. Archive tool and classifier delivered in `dec18c74` on `origin/main`.
+- End-to-end attachment fixture: actual 38 MiB ZIP contents through mocked `getFile`, HTTP streaming, bridge cache, exact message alias, real archive extraction and real text read. Also covers local shared files, cross-chat/missing aliases, retained 900 MiB sparse cache entry, and direct bridge cancellation. Initial focused 49/49 across large attachments, cache and existing admin-alias suites: `/tmp/omnius-wo51-large-attachments.log`.
+- Transport: 25/25 including real FIFO rejection and timer overflow validation: `/tmp/omnius-wo51-telegram-transport-tests.log`; CLI typecheck passed in `/tmp/omnius-wo51-telegram-transport-types.log`.
+- First CLI sweep ran while the two transport follow-up tests were being added. It passed 2,643 cases and failed those two while the module and fixtures were changing; both pass in a fresh run against the final transport source. The final full run passed all 2,656 cases across 278 suites, including the finished transport and dispatch changes: `/tmp/omnius-wo51-cli-final.log`. Command: `pnpm --dir packages/cli exec vitest run --maxWorkers=4 --minWorkers=1`.
+- Clean all-workspace build passed: `/tmp/omnius-wo51-workspace-build.log`. Final all-workspace rebuild passed after the completed source repair: `/tmp/omnius-wo51-final-workspace-build.log`.
+
+## External transport dependency
+
+Telegram documents a hosted Bot API download limit of 20 MB; a Local Bot API server supports downloads without that limit and can return an absolute local file path. Removing Omnius's cap alone cannot change the hosted service. Sources: [File/getFile](https://core.telegram.org/bots/api#file), [Local Bot API server](https://core.telegram.org/bots/api#using-a-local-bot-api-server).
+
+Read-only host review found no local Bot API executable/service/container, configured API app credentials or endpoint. Port 8081 is already used by IPFS. Repository tests use mocked transport; do not claim live large-file reception until a Local Bot API server and its shared files directory are configured. No bot logout, service switch, Telegram message or inference request was performed. The user reserved publication and subsequent live testing; this source workorder does not change that scope.
+
+## Responsive intake closeout
+
+Authoritative polling now schedules a bounded number of attachment dispatch owners outside the poll wait. Deferred ordinary messages stay in the existing SQLite spool, preserving session order across keyset pages. Authenticated, self-targeted controls can bypass a blocked transfer. Stop durably retires its own active attachment and earlier pending session inputs before acknowledgment, including future retries; it never seizes another live dispatch lease. A cancellation fence prevents handler/model startup, and bridge shutdown drains owners before a new generation can start. Downloads and analysis coalesce only within the same session and input, including guest-session isolation. Explicit shadow/disabled durable-intake modes preserve synchronous legacy dispatch because they lack authoritative persistence for safe deferral.
+
+- The full CLI run collected 17 large-attachment cases before the last guest-isolation fixture was added. That final fixture also passed in the subsequent 18-case large-attachment suite; all 2,657 distinct non-skipped CLI cases have a passing result on the final implementation.
+- Final focused regression: 108/108 across nine media, alias, polling, durable-intake, control and spool suites; `/tmp/omnius-wo51-poll-tests.log`. Includes actual blocked-body cancellation while another chat progresses; a cancellation receipt inspected inside the Stop reply callback; no post-Stop handler start; unauthorized/wrong-bot/argument-bearing controls; capacity ordering; restart after a late getFile response; guest/ordinary concurrent same-file cancellation isolation.
+- Spool: 11/11 including 2,106-row keyset paging, update-zero query preservation, future retry cancellation, and foreign lease/terminal-state controls; `/tmp/omnius-wo51-telegram-spool-tests.log`. New owned paths include `telegram-update-spool.ts` and its tests.
+- Initial focused run exposed a zero-ID fixture setup error and an existing transport fixture that stopped polling before returning its deliverable batch. Fixtures were corrected to use valid ingress IDs and stop after actual delivery; delivery assertions remain intact.
+- Independent bounded review passed the final ordering, cancellation durability, deferred retry and guest ownership repairs. No live Telegram, inference, bot migration or service change was performed.
+- Archive implementation is in `dec18c74`; final CLI integration commit includes this workorder. Final delivery hashes are recorded in `TRACKER.md`.