Future security/runtime: enforced isolation for executable NMSh Portable Mods #341

Goal

Define a security-reviewed runtime gate before arbitrary executable Portable Mods can ship.

User/product motivation

Keep declarative context, portable extensions and provider-native ecosystems useful without falsely claiming inert capability inventory is an executable sandbox.

Architecture boundary

Preserve three classes:

1. Context Pack — declarative, from closed [Context Packs] Declarative format, registry, recommendation and integrity model #318 and the NMSh Native module ecosystem and upstream module ports #305 Context Engine.
2. NMSh Portable Mod — target-scoped, capability-brokered.
3. Provider-native mod — executes under provider security, not NMSh's sandbox.
   PR Add keyboard-first managed Claude targets and unified mod inventory #329 creates inventory/capability/inert-broker foundations, not an executable portable loader. Provider-native permissions do not imply portable mod authority.

UX / interaction model

Inventory/provenance clearly distinguishes class, scope, available capabilities and unavailable execution. Future enable/install/run requires explicit reviewed authority. Keyboard-first approval UI, narrow/Safe/NO_COLOR clarity, distinct mod approval owner; never conflate with provider tool.approve.

Security/runtime requirements

Arbitrary portable code never runs in main NMSh process. A worker process alone is not a security sandbox. Require real enforced isolation with documented platform threats and verification before calling execution safe.
Deny filesystem/network/process/secrets by default. Explicit capabilities, resource limits (CPU/memory/time/output), cancellation/termination and cleanup; target isolation; cross-target access explicitly authorized. Broker must mediate all authority, no raw provider handles or implicit host access. Mod approval authority is separate from provider tool.approve.
Review integrity/provenance, dependency loading, installation/update/revocation, platform gaps and malicious escape fixtures. Unsupported isolation means executable support remains disabled.

Dependencies

Post-#329 acceptance, paused behind #328. #305 capability kernel/closed #316, declarative closed #318, #321 security QA, Managed Targets future tracker. Closed #179 ownership boundary.

Non-goals

Implementing executable mods now, marketplace, claiming worker isolation is safe, expanding declarative Context Packs to arbitrary execution, inheriting provider-native approvals.

Acceptance criteria

• Threat model and enforced isolation design reviewed per supported platform.
• Deny-default fs/network/process/secrets demonstrated with adversarial tests.
• Resource/cancellation/cleanup and per-target separation proven.
• Explicit cross-target and independent mod approval authority.
• Honest unsupported-platform behavior and capability inventory.
• No executable feature enabled before security/runtime gates pass.

Architecture boundary

Terminal first, not terminal minimal. NMSh is a terminal-first control/presentation surface over a persistent real shell. Resource navigation does not transfer ownership: tmux owns sessions/windows/panes/PTYs (pseudo-terminals), layout and detach; editors own source editing; GitHub owns remote truth; provider agents own models, reasoning, context/compaction, native tools and the agent loop. NMSh is not a terminal emulator, multiplexer, replacement shell language, editor, browser engine or independent coding-agent harness. See closed #179.

Planning status and sequencing

Future specification only; no implementation is claimed or authorized by this issue. PR #328 is actively being fixed separately. PR #329 is paused until #328 lands and must remain untouched. References to these PRs are dependencies, not requests to amend or merge them. Automated verification and human terminal validation are separate gates.

Related existing issues / PRs

See dependencies and the workspace parent; PR #328 and PR #329 are read-only sequencing references.

Workspace parent

Part of #330. This child owns its focused specification; the parent is the navigation/dependency index.

Related future trackers

#339 Managed Targets future is the immediate dependency tracker; #334 onboarding/inventory must not enable executable support prematurely. Part of workspace program #330.

Future typed presentation / action contributions

Portable Mods need not own an entire standalone panel. Extend this security/runtime tracker with a future API-design note; no separate API issue is needed while these contracts are inseparable from capability mediation and isolation.

Candidate contribution kinds:

• Status item.
• Workspace-sidebar item.
• Right-context-panel content.
• Transcript annotation/transformation.
• Action.
• Approval decoration/explanation.
• Tool annotation.
• Command.
• Search source.
• Context/module fact.
• Notification.

These are conceptual supported contribution kinds, not a promise every kind ships together. Prefer bounded typed contracts through NMSh-owned surfaces. NMSh owns layout, focus, sanitization, accessibility/fallback, action ownership and rendering. Mod supplies bounded typed data/actions under granted capabilities; never mod -> arbitrary ANSI writes or arbitrary renderer ownership.

Define schema/version/validation, stable contribution identity/provenance, target scope, lifecycle/removal, size/rate/resource bounds, freshness and unavailable/error behavior. Actions/commands remain semantic and capability-brokered, not arbitrary callbacks inside the main NMSh process. Search sources and facts do not gain filesystem/network/process/secrets authority merely by registering. Notifications and contributed content do not automatically steal focus.

Transcript annotation/transformation means a bounded NMSh-owned presentation view of eligible owned/structured content, preserving original source/provenance. It does not authorize modifying or semantically recoloring arbitrary raw PTY output, rewriting provider truth, or polluting plain-text /copy and journals with presentation chrome. Review exact eligible content and copy/source semantics before implementation.

Approval decoration/explanation is visibly attributed supplemental content, never replacement authority or a hidden approval decision. It cannot spoof provider approval facts, suppress required choices or inherit provider tool.approve. Provider-native mods execute under provider security and may expose richer native UI that NMSh does not automatically reproduce.

Portable contributions remain target-scoped; cross-target access and global aggregation require explicit grants. Provider agent owns model/reasoning/context-compaction/task planning and state truth/agent loop/native tools. NMSh owns presentation/navigation/typed normalized supported events/input-focus/surface routing/Portable Mod security. Native agent owns the work; NMSh owns how the user interacts with it.

Contribution contract acceptance additions

• Supported contribution kinds use versioned bounded typed validation, provenance and lifecycle contracts.
• NMSh retains rendering/layout/focus/action ownership and complete keyboard/narrow/Safe/NO_COLOR fallback.
• Capability grants and target isolation govern data/actions; registration supplies no implicit authority.
• No arbitrary ANSI/renderer ownership, raw PTY transformation or forged provider/task/approval truth.
• Approval explanations remain attributed and non-authoritative; portable approval is separate.
• Original transcript source and plain-text copy/journal invariants preserved.
• Resource/rate limits and adversarial contribution fixtures extend enforced-isolation review; a worker alone remains insufficient.

Contribution consumers / cross-links

#332 contextual content, task presentation and approval explanations; #336 semantic action controls; #339 provider/task state and target identity. Existing workspace #331, status/tmux #333 and Context Engine #305/#317 are possible consumers, not competing collectors/renderers. Nothing in this note enables executable Portable Mods before this issue's real isolation gates pass.