daggerml 0.1.4__tar.gz → 0.1.6__tar.gz

{daggerml-0.1.4 → daggerml-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: daggerml
-Version: 0.1.4
+Version: 0.1.6
 Summary: DaggerML
 Author-Email: DaggerML <engineering@daggerml.com>
 License: MIT

{daggerml-0.1.4 → daggerml-0.1.6}/docs/extend/adapters.qmd

@@ -124,6 +124,13 @@ ephemeral helper for a nested Docker or Batch adapter: it repeats **invoke** on
 `retry`, then drives nested cleanup after success. It never sends
 `operation="poll"` and cannot coordinate cancellation.
 
+For `--poll` invoke, the helper keeps continuation state private through invoke
+and cleanup, including state returned by terminal invoke. Its final output omits
+`adapter_state`; ordinary CLI calls still forward state unchanged. Nested cleanup
+failure is reported on stderr with execution identity without replacing the
+published invocation outcome. The private state cannot be recovered if that
+ephemeral driver exits unexpectedly.
+
 Register one class per installed entry point. The entry-point key is descriptive;
 lookup uses the class's `name`. Discovery is lazy, retains loaded objects, warns
 on duplicates with the last registration winning, and raises `DmlRepoError` on a

{daggerml-0.1.4 → daggerml-0.1.6}/docs/extend/executors.qmd

@@ -115,6 +115,19 @@ invoke, cleanup, and cancel operations to its nested adapter. Docker and Batch
 are wrappers that own detached job state and resource teardown while their
 nested adapter runs in the detached environment.
 
+Script and Docker launch state includes `owner`, formatted as
+`effective-UID@hostname` in the environment where that executor starts.
+Poll, cleanup, and cancel from a different user or hostname
+return retry with unchanged state before accessing local resources. Distinct
+hosts and containers must use distinct hostnames; ownership is not authentication
+or automatic failover. Ownerless or hostname-only saved state is unsupported.
+
+Script uses the same detached supervisor path inside and outside Docker. Docker
+retains its own owner/container/image state when returning nested outcomes; its
+container's `--poll` driver privately maintains child continuation through
+cleanup. SSH forwards state unchanged, so either caller can drive an SSH-wrapped
+execution on the same owning destination. Batch has no local ownership restriction.
+
 Use the supplied remote scratch URI for detached input/output, not process-local
 handoff state. Runtime coordination records own durable execution state, shared
 retry timing, locking, result, lineage, cancellation, and invalidation.

{daggerml-0.1.4 → daggerml-0.1.6}/docs/use/execution.qmd

@@ -89,6 +89,11 @@ the Lambda adapter. SSH can source `env_files`; Batch additionally needs a
 Lambda integration, container image, queues, task role, and AWS credentials.
 Other schedulers or cloud integrations require an installed extension.
 
+Script and local Docker continuation/teardown must run on their launching
+environment, identified by `effective-UID@hostname`; other users/hosts safely retry. Use distinct
+host/container names. SSH callers may differ when they reach the same owning
+destination and effective user. Ownerless or hostname-only saved adapter state is unsupported.
+
 <!-- docs:pseudocode: An SSH host, scheduler, or cloud adapter is not owned by the documentation fixture. Configure its credentials and installed integration before composing this wrapper. -->
 ```python
 remote_docker = api.funkify(

{daggerml-0.1.4 → daggerml-0.1.6}/docs/use/runtimes.qmd

@@ -39,6 +39,11 @@ lifecycle, lineage, cancellation, invalidation, adapter continuation, shared
 retry deadlines, and cleanup. Cleanup may remain pending or fail without making
 an otherwise reusable result unavailable.
 
+For script and local Docker, the launching effective user and hostname must
+participate in polling, cleanup, and cancellation. Other users/hosts return retry without touching local
+resources; there is no automatic takeover. A published result remains reusable
+while owner-dependent cleanup is pending.
+
 ```{bash}
 course_ref="$(dml show | jq -er '.dags["course-execution"]')"
 first_ref="$(dml dag get-node-by-name "$course_ref" script-first)"

daggerml-0.1.6/openspec/changes/archive/2026-10-06-local-executor-ownership/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-10-06

daggerml-0.1.6/openspec/changes/archive/2026-10-06-local-executor-ownership/design.md

@@ -0,0 +1,123 @@
+## Context
+
+See [proposal.md](proposal.md) for motivation. Core already persists opaque `adapter_state` in the execution's S3 driver record and supplies it to invoke, cleanup, and cancel. No additional persistence mechanism is needed.
+
+Script launches a detached supervisor and returns its PID and local file paths. Docker returns a local-daemon container ID and temporary image reference, then runs its nested adapter with `--poll`. SSH forwards adapter operations and state without owning detached work. Batch also uses the nested `--poll` driver, but its own resources are remotely addressable.
+
+Currently `AdapterBase.cli()` feeds retry state back into invoke, but its final response includes nested state. It also replaces the invocation response with the cleanup response and does not capture terminal invoke state updates before cleanup. Docker terminal polling returns the child's response directly rather than preserving its own state.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Prevent a different execution environment from inspecting, signaling, or deleting local script/Docker resources.
+- Use flat launch state and the existing detached polling boundary, without special script behavior inside Docker.
+- Keep SSH transparent and separate published invocation outcomes from cleanup diagnostics.
+- Keep the implementation small and require the new state contract without compatibility branches.
+
+**Non-Goals:**
+
+- Ownership trees, executor-state stacks, new S3 state records, or changes to core execution/cache coordination.
+- Automatic takeover, remote routing to an owner, polling-driver recovery, or new cancellation propagation.
+- Ownership restrictions on SSH or Batch, shared/remote Docker daemon identification, boot-epoch/PID-reuse protection, or a new machine-identity service.
+- Changes to execution scratch-path allocation.
+
+## Decisions
+
+### 1. Flat owner state identifies the environment that launches local work
+
+Use `f"{os.geteuid()}@{socket.gethostname()}"` through a small private contrib helper, evaluated in the adapter process where script or Docker actually starts. The effective UID distinguishes users on the same machine without trusting username environment variables. This identity survives fresh adapter processes under the same effective user and requires no configuration, dependency, new files, or remote writes. Distinct hosts/containers must have distinct hostnames; default Docker container hostnames naturally distinguish containers from their host.
+
+Script state becomes:
+
+```json
+{"owner":"1000@host-A","pid":123,"workdir":"...","result_path":"...","stdout_path":"...","stderr_path":"..."}
+```
+
+Docker state becomes:
+
+```json
+{"owner":"1000@host-A","container_id":"...","cleanup_image":null}
+```
+
+The identifier is not the runtime driver's lock-owner token and is not part of the runnable or cache key. Keep all backend fields at their existing level and preserve other continuation fields.
+
+Alternatives: one execution-wide owner incorrectly pins SSH callers; per-process UUIDs break fresh-process polling; persistent machine tokens and structured ownership envelopes add machinery not needed for this change.
+
+### 2. Guard local operations before any resource access
+
+For object state, script and Docker compare required `state["owner"]` with the current environment before PID probes, file reads/removal, Docker executable discovery, or daemon commands. A different owner returns `{"status":"retry","adapter_state":state,"error":null}` through the normal executor response normalization. Do not claim success/cancelled, rewrite the owner, launch replacement work, or add special retry timing.
+
+The guard applies to invoke continuation, cleanup, and cancel, including operations after result publication. Matching-owner behavior remains unchanged. Null-state cleanup/cancel retains its existing no-resource semantics; saved object state requires the new owner field. There is no ownerless-state fallback or migration.
+
+The helper stays inside contrib. Do not add an ownership rule to `ExecutorBase`, because SSH must remain able to forward a remote executor's state from any calling machine.
+
+### 3. The nested polling driver owns private continuation state
+
+Change only the `--poll` invoke flow in `AdapterBase.cli()`:
+
+1. Maintain the latest returned state locally, including state returned by terminal invoke. An omitted state field retains the last state; an explicit null replaces it.
+2. Feed that state into repeated invoke and, after successful publication, into cleanup.
+3. Maintain cleanup continuation independently while following the existing cleanup retry loop.
+4. Once invoke and any required nested cleanup finish, emit the terminal invocation outcome without `adapter_state`.
+
+Do not strip state in ordinary non-`--poll` calls or when a request has not completed this private invoke lifecycle. This preserves SSH forwarding and normal runtime continuation. Script has no awareness of `--poll`, Docker, or whether its returned state will be persisted to S3 or retained in a caller's memory.
+
+Alternatives: changing script to synchronous execution inside Docker would create two execution paths; persisting every nested layer centrally would require a new state-composition protocol.
+
+### 4. Docker returns only its own continuation state
+
+Docker validates the nested terminal response, forwards its invocation status/error, discards any child continuation state, and attaches the original Docker state on every valid terminal outcome. Error paths with valid launch state also preserve that state. This retains owner, container ID, and image cleanup information for subsequent wrapper operations.
+
+Batch's existing job-state handling remains compatible with child terminal responses that omit `adapter_state`; it needs no ownership restriction or new nested state. Verify that behavior in tests because the CLI change also affects Batch's nested driver.
+
+### 5. Cleanup does not replace invocation outcome
+
+Keep separate invocation and cleanup responses in the nested driver. Cleanup retries update only its private cleanup continuation. Terminal cleanup failure or an exception emits a diagnostic to stderr containing execution identity and the failure, while final output retains the invocation's status/error. Do not add new JSON response fields or write nested cleanup outcomes into core-owned execution files.
+
+Keep the existing successful-invoke requirement for a published result before cleanup. Missing publication is still an invocation protocol error, not a cleanup warning. This change does not add a new cleanup lifecycle for failed nested invocations.
+
+### 6. Composition follows detached boundaries, not runnable depth
+
+| Runnable chain | Durable state received by the runtime caller | Private state |
+| --- | --- | --- |
+| `script` on A | Script owner A and launch state | None |
+| `docker -> script` on A | Docker owner A and launch state | Container's `--poll` driver retains script state owned by that container |
+| `ssh -> docker -> script`, SSH destination C | Docker owner C and launch state, transparently forwarded by SSH | Container's `--poll` driver retains script state |
+| `docker -> ssh -> script` on A, SSH destination C | Docker owner A and launch state | Container's `--poll` driver retains script owner C and forwards operations to C |
+
+Additional detached wrappers apply the same rule locally. No layer accumulates another layer's owner fields.
+
+## Risks / Trade-offs
+
+- [Duplicate hostnames] -> Treat distinct host/container names as an operating requirement and document it; do not present hostname ownership as authentication or a security boundary.
+- [Owner disappears or its hostname/effective user changes] -> Other users/machines retry without touching local resources. No automatic failover is promised; publication can still make an existing result reusable, while cleanup/cancel may need owner participation.
+- [Private driver exits unexpectedly] -> Its child continuation is lost. This is the existing ephemeral-driver limitation, not a durable recovery protocol.
+- [Outer teardown leaves SSH-launched work running] -> Keep existing cancellation behavior and explicitly avoid claiming that container removal guarantees remote descendant teardown.
+- [Owner-mismatch retries affect shared retry deadlines] -> Use the existing default retry policy; do not add long delays that unnecessarily block the actual owner.
+- [Nested cleanup failure cannot be retained as per-layer S3 diagnostics] -> Report it on stderr without overwriting invocation success. Outer cleanup retains its existing separately coordinated outcome.
+- [Mixed versions or ownerless saved state] -> Unsupported by explicit user decision. No fallback, dual-write, or legacy ownership guessing.
+
+## Validation
+
+Use contract tests to simulate A/B/C identities without provisioning multiple hosts. Assert that owner mismatches invoke no local resource functions for poll, cleanup, or cancel; fresh adapter instances with the same owner continue normally. Exercise private invoke/cleanup state updates, hidden terminal state, unchanged ordinary CLI responses, Docker wrapper-state preservation, and cleanup failure/exception diagnostics.
+
+Verify SSH transparently forwards C-owned state from callers A and B, and Batch accepts state-free nested terminal responses while retaining job state. Use focused process/Docker integration tests for identical script behavior in both environments, recording unavailable infrastructure as unverified.
+
+## References
+
+- `DOC_MAP.md`
+- `CONTRIBUTING.md`
+- `docs/start-here/index.qmd`
+- `docs/extend/adapters.qmd`
+- `docs/extend/executors.qmd`
+- `docs/use/execution.qmd`
+- `docs/use/runtimes.qmd`
+- `src/daggerml/README.md`
+- `src/daggerml/_core/README.md`
+- `openspec/README.md`
+- `openspec/spec-overview.md`
+- `openspec/specs/adapter-operation-protocol/spec.md`
+- `openspec/specs/executor-cancellation/spec.md`
+- `openspec/specs/execution-state/spec.md`
+- `openspec/specs/docker-image-artifacts/spec.md`

daggerml-0.1.6/openspec/changes/archive/2026-10-06-local-executor-ownership/proposal.md

@@ -0,0 +1,31 @@
+## Why
+
+When multiple machines share an execution cache, a caller can receive another machine's script PID or Docker container ID and incorrectly inspect or tear down its own local resources. Detached wrapper execution also leaks nested continuation state and can replace a successful invocation outcome with a cleanup failure.
+
+## What Changes
+
+- Add a flat execution-environment `owner` identifier to script and Docker launch state, persisted through the existing adapter-state protocol.
+- Gate script and Docker poll, cleanup, and cancellation on that owner; a different environment returns retry with unchanged state without touching local resources.
+- Keep script execution identical inside and outside containers. The nested adapter's `--poll` driver privately retains continuation state through invoke and cleanup, then omits it from its terminal output.
+- Preserve Docker's own state when returning a nested invocation outcome.
+- Preserve the invocation outcome independently of nested cleanup; report cleanup failure on stderr without converting published success into invocation failure.
+- Leave normal, non-`--poll` CLI state forwarding and SSH transport unchanged. Do not add ownership restrictions to Batch.
+
+## Capabilities
+
+### New Capabilities
+
+- `local-executor-ownership`: execution-environment ownership for script and Docker state and safe handling of requests from another environment.
+
+### Modified Capabilities
+
+- `adapter-operation-protocol`: private continuation handling and terminal state omission for the nested `--poll` invocation driver, plus preservation of Docker wrapper state.
+- `executor-cancellation`: nested cleanup completion and diagnostics remain independent of the terminal invocation outcome.
+
+## Impact
+
+- Implementation: `src/daggerml/contrib/executors/script.py`, `src/daggerml/contrib/executors/docker.py`, `src/daggerml/contrib/adapters.py`, and a small private ownership helper in contrib.
+- Coverage: script, nested-executor, adapter CLI, SSH-forwarding, and Batch compatibility contract tests; focused local-process/Docker integration coverage where available.
+- Documentation: `docs/extend/adapters.qmd`, `docs/extend/executors.qmd`, and the relevant execution/runtime guidance.
+- No new S3 records, core lifecycle changes, wire fields, runnable/cache identity changes, dependencies, or nested adapter-state schema.
+- **BREAKING**: script and Docker continuation state requires `owner` formatted as `effective-UID@hostname`; ownerless or hostname-only state is unsupported, with no backward-compatibility path. Distinct hosts/containers require distinct hostnames.

daggerml-0.1.6/openspec/changes/archive/2026-10-06-local-executor-ownership/specs/adapter-operation-protocol/spec.md

@@ -0,0 +1,53 @@
+## ADDED Requirements
+
+### Requirement: Ephemeral polling invocation drivers SHALL retain private continuation state
+
+A nested adapter CLI invocation using `--poll` SHALL retain returned adapter state privately through repeated invoke and required nested cleanup calls. A returned state field, including terminal invoke state, SHALL replace the current private state; an omitted field SHALL preserve the prior state and explicit null SHALL clear it. Cleanup retries SHALL use their latest private continuation. After completing this private invocation lifecycle, the CLI SHALL omit `adapter_state` from its terminal output to the wrapper. Ordinary CLI calls without `--poll` SHALL preserve state forwarding, and requests outside this private invocation lifecycle SHALL retain their existing response contract.
+
+#### Scenario: Invoke retries reuse private continuation
+- **WHEN** a nested `--poll` invoke returns retry with object state
+- **THEN** the next invoke receives that state
+- **AND** the driver does not emit an intermediate response to its wrapper
+
+#### Scenario: Terminal invoke state is used for cleanup
+- **WHEN** a successful terminal invoke returns updated adapter state
+- **THEN** nested cleanup receives the updated state rather than the preceding retry's state
+
+#### Scenario: Omitted terminal state retains the last continuation
+- **WHEN** a terminal invoke omits adapter state after a prior retry
+- **THEN** the driver retains the preceding private state for cleanup
+
+#### Scenario: Explicit null clears continuation
+- **WHEN** a terminal invoke explicitly returns null adapter state
+- **THEN** the driver supplies null state to cleanup rather than reusing a preceding retry state
+
+#### Scenario: Cleanup retries remain private
+- **WHEN** nested cleanup returns retry with updated state
+- **THEN** the next cleanup receives that state
+- **AND** the state is not emitted to the wrapper when cleanup finishes
+
+#### Scenario: Terminal private invocation output hides continuation
+- **WHEN** the `--poll` invocation lifecycle finishes with a terminal success or failure outcome
+- **THEN** its output contains that invocation status and diagnostics without adapter state
+
+#### Scenario: Ordinary CLI response forwards continuation
+- **WHEN** the adapter CLI is called without `--poll`
+- **THEN** its output retains the operation's returned adapter state unchanged
+
+### Requirement: Docker terminal responses SHALL preserve wrapper continuation
+
+When Docker obtains a valid terminal nested invocation response, it SHALL forward the nested invocation outcome while returning its own saved adapter state to its caller. It SHALL NOT substitute nested adapter state for wrapper owner, container ID, temporary image reference, or other wrapper continuation fields. Error responses produced with valid wrapper launch state SHALL also preserve that state. Nested output validation SHALL retain the existing adapter response contract.
+
+#### Scenario: Nested success retains Docker ownership and resource identifiers
+- **WHEN** Docker reads a valid successful nested response that omits adapter state
+- **THEN** Docker returns success with its original wrapper state
+- **AND** later cleanup receives the wrapper owner and container/image identifiers
+
+#### Scenario: Nested failure retains Docker cleanup state
+- **WHEN** Docker reads a valid terminal failure from its nested adapter
+- **THEN** it forwards the failure status and error with its own wrapper state
+
+#### Scenario: Child continuation cannot replace Docker state
+- **WHEN** a valid terminal nested response includes child adapter state
+- **THEN** Docker does not expose that child state as its own continuation
+- **AND** it returns its original wrapper state

daggerml-0.1.6/openspec/changes/archive/2026-10-06-local-executor-ownership/specs/executor-cancellation/spec.md

@@ -0,0 +1,28 @@
+## MODIFIED Requirements
+
+### Requirement: Ephemeral nested adapter drivers SHALL finish nested cleanup
+
+When Docker or Batch runs a nested adapter in an ephemeral environment using its internal polling loop, that nested driver SHALL complete or terminally report nested cleanup before the environment exits. The driver SHALL preserve its terminal invocation outcome independently of cleanup responses. Terminal cleanup failure or a cleanup exception SHALL emit stderr diagnostics identifying the execution and failure and SHALL NOT replace successful invocation status or diagnostics. Outer cleanup SHALL independently prune the wrapper container, job, image, or job definition. Missing result publication after a successful invoke SHALL remain an invocation protocol error, not a cleanup warning.
+
+#### Scenario: Containerized nested execution completes
+- **WHEN** a nested adapter publishes its result inside Docker execution
+- **THEN** the nested driver performs nested cleanup before exiting
+- **AND** outer Docker cleanup later removes wrapper resources
+
+#### Scenario: Nested cleanup retries do not become invocation outcomes
+- **WHEN** a successful nested invoke is followed by cleanup retries and eventual cleanup success
+- **THEN** the driver retains the successful invocation outcome while finishing cleanup
+
+#### Scenario: Terminal cleanup failure preserves published invocation success
+- **WHEN** a successful published nested invoke is followed by terminal cleanup failure
+- **THEN** the driver emits stderr diagnostics identifying the execution and cleanup failure
+- **AND** its terminal invocation output remains successful
+
+#### Scenario: Cleanup exception preserves published invocation success
+- **WHEN** cleanup raises after a successful published nested invoke
+- **THEN** the driver reports the cleanup exception on stderr and retains the successful invocation output
+
+#### Scenario: Missing publication is not hidden as cleanup failure
+- **WHEN** a nested invoke reports success without a published result
+- **THEN** the driver treats the missing publication as an invocation protocol error
+- **AND** it does not downgrade that error to a cleanup warning

daggerml-0.1.6/openspec/changes/archive/2026-10-06-local-executor-ownership/specs/local-executor-ownership/spec.md

@@ -0,0 +1,71 @@
+## Purpose
+
+Define safe continuation and resource teardown for script and Docker executions shared by callers on different machines, without changing transparent transports or remotely addressable executors.
+
+## ADDED Requirements
+
+### Requirement: Local launch state SHALL identify its owning execution environment
+
+Script and Docker SHALL include a required nonempty string `owner` in the adapter state returned when launching detached work. Owner identity SHALL be stable across fresh adapter processes in the same execution environment. Participating host/container environments SHALL use distinct owner identities. Backend launch fields and other continuation fields SHALL remain preserved. Ownership SHALL NOT change runnable identity or cache identity. Saved object state without `owner` SHALL be unsupported; no compatibility fallback SHALL infer or claim ownership.
+
+#### Scenario: Launch identifies the environment performing the work
+- **WHEN** script or Docker starts detached work on environment A
+- **THEN** its returned adapter state contains owner A and the executor's backend launch fields
+
+#### Scenario: Fresh process retains the same ownership identity
+- **WHEN** another adapter process on environment A receives A-owned launch state
+- **THEN** it identifies itself as the same owner and can continue the existing work
+
+#### Scenario: Containerized script identifies its own environment
+- **WHEN** script launches inside a Docker container
+- **THEN** script returns the container environment's owner identity using the same launch contract as direct script execution
+- **AND** that identity is distinct from the host's Docker owner identity
+
+### Requirement: Ownership SHALL distinguish effective users on the same host
+
+The owner identifier SHALL have format `<effective UID>@<hostname>`, resolved in the execution environment where the executor runs. Different effective users on the same hostname SHALL have different owner identifiers. Username environment variables SHALL NOT determine identity. Ownerless or hostname-only saved state SHALL NOT receive a compatibility fallback.
+
+#### Scenario: Different users share a host
+- **WHEN** two executor processes run on the same hostname with different effective UIDs
+- **THEN** they produce different owner identifiers
+- **AND** neither can pass the other's local-resource ownership check
+
+#### Scenario: Username environment variables do not change ownership
+- **WHEN** the username environment changes without changing effective UID or hostname
+- **THEN** the owner identifier remains unchanged
+
+### Requirement: Local resource operations SHALL require matching ownership
+
+For saved object state, script and Docker SHALL check its required owner before any local resource inspection or teardown during invoke continuation, cleanup, or cancel. A different owner SHALL return status `retry`, unchanged object `adapter_state`, and null error without inspecting or modifying local processes, files, containers, or images. It SHALL NOT replace ownership, launch substitute work, report completed cleanup, or confirm cancellation. Matching ownership SHALL retain existing backend behavior. Null-state cleanup and cancellation SHALL retain their existing no-resource behavior.
+
+#### Scenario: Different machine polls shared state
+- **WHEN** environment B receives A-owned script or Docker state for an invoke continuation
+- **THEN** it returns retry with that state unchanged
+- **AND** it performs no local resource access
+
+#### Scenario: Different machine attempts published-result cleanup
+- **WHEN** environment B receives A-owned script or Docker state for cleanup
+- **THEN** it returns retry without deleting resources or reporting cleanup success
+- **AND** it preserves all continuation fields
+
+#### Scenario: Different machine attempts cancellation
+- **WHEN** environment B receives A-owned script or Docker state for cancel
+- **THEN** it returns retry without signaling a process or stopping/removing a container
+- **AND** it does not return cancelled
+
+#### Scenario: Owning environment continues local operations
+- **WHEN** environment A receives A-owned state for continuation, cleanup, or cancellation
+- **THEN** the existing backend operation proceeds against A's resources
+
+### Requirement: Transparent transports SHALL NOT pin ownership to their caller
+
+SSH SHALL forward operations and nested adapter state unchanged to its configured destination without adding a caller owner. Local ownership restrictions SHALL apply where script or Docker actually executes, not to the entire runnable chain. Batch SHALL NOT acquire a local-machine ownership restriction.
+
+#### Scenario: Two callers reach the same owning SSH destination
+- **WHEN** A and B call an SSH-wrapped Docker or script execution on C with C-owned saved state
+- **THEN** each forwards that state to C
+- **AND** the nested executor on C accepts its matching ownership
+
+#### Scenario: Batch continuation is independent of the original caller
+- **WHEN** another caller checks an existing Batch execution using its saved job state
+- **THEN** no script/Docker local-owner restriction is imposed on the Batch executor

daggerml-0.1.6/openspec/changes/archive/2026-10-06-local-executor-ownership/tasks.md

@@ -0,0 +1,45 @@
+## 1. Local script ownership
+
+Contract: `specs/local-executor-ownership/spec.md`. Add only a private contrib helper `_current_owner() -> str`, returning `f"{os.geteuid()}@{socket.gethostname()}"`. Script launch state remains an object containing its existing fields plus required `owner: str`. Wire requests and method signatures remain unchanged, as defined in `openspec/specs/adapter-operation-protocol/spec.md`. Nonowner responses normalize to `{"status":"retry","adapter_state":<unchanged state>,"error":null}`.
+
+- [x] 1.1 Add the private hostname helper and script launch ownership. Guard object-state poll, cleanup, and cancel before local resource access; keep null-state no-resource behavior and add no ownerless-state fallback. Update the script contract tests with valid owner-bearing state and cases covering launch identity, fresh matching-owner processes, and nonowner operations that perform no PID/file access.
+- [x] 1.2 Validate the script checkpoint with `uv run --dev --all-extras pytest tests/contrib/contracts/test_script_executor_contract.py tests/contrib/contracts/test_nested_executor_protocol_contract.py -m 'not slow'`. Assert unchanged state and retry on mismatch, existing matching-owner success/failure/cancel behavior, and a required owner on launch. Update any synthetic script state in affected core contract tests without adding compatibility logic.
+
+## 2. Docker ownership and wrapper-state preservation
+
+Depends on section 1's helper. Contracts: `specs/local-executor-ownership/spec.md` and the Docker terminal-response requirement in `specs/adapter-operation-protocol/spec.md`. Docker state is `{"owner":str,"container_id":str,"cleanup_image":str|null,...}`; retain all existing continuation fields. A valid terminal nested outcome is returned with the original Docker adapter state, never the child's. No Docker/SSH/Batch runnable or request schema changes.
+
+- [x] 2.1 Add Docker launch ownership and guard object-state poll, cleanup, and cancel before Docker discovery/commands or resource changes. Preserve the wrapper state on valid nested success/failure and local error responses with valid launch state. Add contract cases asserting that nonowner operations execute no local commands and that child adapter state cannot overwrite Docker owner/container/image fields.
+- [x] 2.2 Validate with `uv run --dev --all-extras pytest tests/contrib/contracts/test_nested_executor_protocol_contract.py tests/_core/contracts/test_flaky_ci_reproducers.py -m 'not slow'`. Cover matching-owner lifecycle behavior, all three mismatch operations, state-free nested terminal output, nested output with child state, nested failure, and malformed nested output retaining existing protocol-error behavior. Update other affected synthetic Docker launch states to include owner.
+
+## 3. Private polling continuation and independent cleanup outcome
+
+Depends on section 2 so hidden child state cannot erase Docker continuation. Contracts: `specs/adapter-operation-protocol/spec.md` and `specs/executor-cancellation/spec.md`. Scope is `AdapterBase.cli()`'s private `--poll` invoke lifecycle; its `cli(argv: list[str] | None = None) -> int` signature and stdin/stdout/S3 transport remain unchanged. Terminal private output contains invocation status/error without `adapter_state`. Non-`--poll` responses and operations outside the private invocation lifecycle retain their existing shape.
+
+- [x] 3.1 Retain latest invocation state through all responses, including terminal updates, omitted fields, and explicit null. Feed the resulting state to required nested cleanup, keep cleanup continuation independent, and omit state only from completed private invocation output. Add adapter CLI contract cases for each state transition and unchanged ordinary CLI forwarding.
+- [x] 3.2 Preserve terminal invocation outcome separately from cleanup responses. Finish cleanup retries, report terminal cleanup failure/exception to stderr with execution identity, and retain invocation success/error in final output. Add cases for cleanup success, state-changing retries, failure codes, exceptions, failed invoke output, and missing result publication remaining a protocol error. Do not add cleanup after failed invocation or new JSON fields.
+- [x] 3.3 Validate with `uv run --dev --all-extras pytest tests/contrib/contracts/test_adapter_runtime_contract.py tests/contrib/contracts/test_nested_executor_protocol_contract.py tests/contrib/contracts/test_aws_client_resilience_contract.py -m 'not slow'`. Assert hidden state on private success/failure, latest state in cleanup, stderr-only cleanup diagnostics, unchanged non-`--poll` state, preserved Docker wrapper state, and Batch job-state retention for nested output without adapter state.
+
+## 4. Composition and process-boundary validation
+
+Depends on sections 1–3. SSH forwarding and Batch ownership policy remain unchanged. Use A/B/C hostname mocks rather than adding a multi-host test harness. Integration scenarios retain existing slow/docker markers, bounded subprocess lifetimes, and fixture-owned teardown.
+
+- [x] 4.1 Add or update SSH contract coverage showing that A and B forward C-owned script/Docker state unchanged and ownership is checked on C, not by the caller transport. Validate with `uv run --dev --all-extras pytest tests/contrib/contracts/test_ssh_executor_contract.py -m 'not slow'`; assert no SSH wrapper owner or new nesting state.
+- [x] 4.2 Update owner-bearing state in `tests/contrib/integration/test_local_process_integration.py` and `tests/contrib/integration/test_docker_lifecycle_integration.py`. Assert script executes through its normal detached supervisor path in both environments, fresh adapter processes recognize the same owner, Docker durable state remains host-owned, and child terminal handoff omits state. Run `uv run --dev --all-extras pytest tests/contrib/integration/test_local_process_integration.py` and `uv run --dev --all-extras pytest tests/contrib/integration/test_docker_lifecycle_integration.py -m docker` where infrastructure is available; record skips/unrun checks as unverified.
+
+Integration result: 3 local-process tests passed; 5 Docker cases skipped because Docker and `LIFECYCLE_DOCKER_IMAGE` were unavailable. Docker end-to-end behavior remains unverified locally.
+
+## 5. Documentation and completion checks
+
+Depends on the preceding behavior checkpoints. Keep documentation focused on ownership, the private polling boundary, and independent cleanup. No unrelated refactors, scratch allocation changes, dependencies, or legacy-state migration.
+
+- [x] 5.1 Update `docs/extend/adapters.qmd` and `docs/extend/executors.qmd` for hidden private state, hostname ownership, unchanged SSH forwarding, wrapper-state preservation, and stderr cleanup diagnostics. Add narrowly necessary notes to `docs/use/execution.qmd` / `docs/use/runtimes.qmd` about owner participation in local polling/teardown, distinct host/container names, and unsupported ownerless state. Check examples against the unchanged public request/response schema.
+- [x] 5.2 Run `openspec validate local-executor-ownership --strict`, then the required implementation finish sequence in order: `uv run --dev pyright`, `uv run --dev ruff check --fix .`, and `uv run --dev pytest -m 'not slow' .`. Review any lint edits and require all three code checks to pass; report infrastructure-dependent checks separately.
+
+Completion result: strict OpenSpec validation, Pyright, and Ruff passed. The non-slow suite passed with 762 passed and 2 existing expected failures (136 deselected). The focused contrib/core contract run passed with 138 passed and 2 existing expected failures. Docker integration remains unverified as noted above.
+
+Commit expectation: no commit or push during proposal authoring. When implementation commits are requested, keep each behavior checkpoint focused and include its matching tests; do not include unrelated work.
+
+User-requested refinement: ownership now uses effective UID plus hostname. Contract tests cover a different effective user on the same host, the same effective user on a different host, and independence from username environment variables. No hostname-only compatibility path is added.
+
+Refinement validation: Pyright and Ruff passed; the non-slow suite passed with 769 passed and 2 existing expected failures (136 deselected).

{daggerml-0.1.4 → daggerml-0.1.6}/openspec/specs/adapter-operation-protocol/spec.md

@@ -134,3 +134,55 @@ The `daggerml._core` package facade SHALL export the canonical adapter-response
 - **WHEN** an adapter or executor validates an operation response
 - **THEN** it can import the canonical validator directly from `daggerml._core`
 - **AND** validation preserves the existing operation-specific status, state, delay, and error rules
+
+### Requirement: Ephemeral polling invocation drivers SHALL retain private continuation state
+
+A nested adapter CLI invocation using `--poll` SHALL retain returned adapter state privately through repeated invoke and required nested cleanup calls. A returned state field, including terminal invoke state, SHALL replace the current private state; an omitted field SHALL preserve the prior state and explicit null SHALL clear it. Cleanup retries SHALL use their latest private continuation. After completing this private invocation lifecycle, the CLI SHALL omit `adapter_state` from its terminal output to the wrapper. Ordinary CLI calls without `--poll` SHALL preserve state forwarding, and requests outside this private invocation lifecycle SHALL retain their existing response contract.
+
+#### Scenario: Invoke retries reuse private continuation
+- **WHEN** a nested `--poll` invoke returns retry with object state
+- **THEN** the next invoke receives that state
+- **AND** the driver does not emit an intermediate response to its wrapper
+
+#### Scenario: Terminal invoke state is used for cleanup
+- **WHEN** a successful terminal invoke returns updated adapter state
+- **THEN** nested cleanup receives the updated state rather than the preceding retry's state
+
+#### Scenario: Omitted terminal state retains the last continuation
+- **WHEN** a terminal invoke omits adapter state after a prior retry
+- **THEN** the driver retains the preceding private state for cleanup
+
+#### Scenario: Explicit null clears continuation
+- **WHEN** a terminal invoke explicitly returns null adapter state
+- **THEN** the driver supplies null state to cleanup rather than reusing a preceding retry state
+
+#### Scenario: Cleanup retries remain private
+- **WHEN** nested cleanup returns retry with updated state
+- **THEN** the next cleanup receives that state
+- **AND** the state is not emitted to the wrapper when cleanup finishes
+
+#### Scenario: Terminal private invocation output hides continuation
+- **WHEN** the `--poll` invocation lifecycle finishes with a terminal success or failure outcome
+- **THEN** its output contains that invocation status and diagnostics without adapter state
+
+#### Scenario: Ordinary CLI response forwards continuation
+- **WHEN** the adapter CLI is called without `--poll`
+- **THEN** its output retains the operation's returned adapter state unchanged
+
+### Requirement: Docker terminal responses SHALL preserve wrapper continuation
+
+When Docker obtains a valid terminal nested invocation response, it SHALL forward the nested invocation outcome while returning its own saved adapter state to its caller. It SHALL NOT substitute nested adapter state for wrapper owner, container ID, temporary image reference, or other wrapper continuation fields. Error responses produced with valid wrapper launch state SHALL also preserve that state. Nested output validation SHALL retain the existing adapter response contract.
+
+#### Scenario: Nested success retains Docker ownership and resource identifiers
+- **WHEN** Docker reads a valid successful nested response that omits adapter state
+- **THEN** Docker returns success with its original wrapper state
+- **AND** later cleanup receives the wrapper owner and container/image identifiers
+
+#### Scenario: Nested failure retains Docker cleanup state
+- **WHEN** Docker reads a valid terminal failure from its nested adapter
+- **THEN** it forwards the failure status and error with its own wrapper state
+
+#### Scenario: Child continuation cannot replace Docker state
+- **WHEN** a valid terminal nested response includes child adapter state
+- **THEN** Docker does not expose that child state as its own continuation
+- **AND** it returns its original wrapper state

{daggerml-0.1.4 → daggerml-0.1.6}/openspec/specs/executor-cancellation/spec.md

@@ -75,9 +75,28 @@ Normal terminal invoke handling SHALL not be the sole teardown path. Script clea
 - **THEN** executor cancellation tears down its resources without requiring cleanup first
 
 ### Requirement: Ephemeral nested adapter drivers SHALL finish nested cleanup
-When Docker or Batch runs a nested adapter in an ephemeral environment using its internal polling loop, that nested driver SHALL complete or terminally record nested cleanup before the environment exits. Outer cleanup SHALL independently prune the wrapper container, job, image, or job definition.
+
+When Docker or Batch runs a nested adapter in an ephemeral environment using its internal polling loop, that nested driver SHALL complete or terminally report nested cleanup before the environment exits. The driver SHALL preserve its terminal invocation outcome independently of cleanup responses. Terminal cleanup failure or a cleanup exception SHALL emit stderr diagnostics identifying the execution and failure and SHALL NOT replace successful invocation status or diagnostics. Outer cleanup SHALL independently prune the wrapper container, job, image, or job definition. Missing result publication after a successful invoke SHALL remain an invocation protocol error, not a cleanup warning.
 
 #### Scenario: Containerized nested execution completes
 - **WHEN** a nested adapter publishes its result inside Docker execution
 - **THEN** the nested driver performs nested cleanup before exiting
 - **AND** outer Docker cleanup later removes wrapper resources
+
+#### Scenario: Nested cleanup retries do not become invocation outcomes
+- **WHEN** a successful nested invoke is followed by cleanup retries and eventual cleanup success
+- **THEN** the driver retains the successful invocation outcome while finishing cleanup
+
+#### Scenario: Terminal cleanup failure preserves published invocation success
+- **WHEN** a successful published nested invoke is followed by terminal cleanup failure
+- **THEN** the driver emits stderr diagnostics identifying the execution and cleanup failure
+- **AND** its terminal invocation output remains successful
+
+#### Scenario: Cleanup exception preserves published invocation success
+- **WHEN** cleanup raises after a successful published nested invoke
+- **THEN** the driver reports the cleanup exception on stderr and retains the successful invocation output
+
+#### Scenario: Missing publication is not hidden as cleanup failure
+- **WHEN** a nested invoke reports success without a published result
+- **THEN** the driver treats the missing publication as an invocation protocol error
+- **AND** it does not downgrade that error to a cleanup warning

daggerml-0.1.6/openspec/specs/local-executor-ownership/spec.md

@@ -0,0 +1,71 @@
+## Purpose
+
+Define safe continuation and resource teardown for script and Docker executions shared by callers on different machines, without changing transparent transports or remotely addressable executors.
+
+## Requirements
+
+### Requirement: Local launch state SHALL identify its owning execution environment
+
+Script and Docker SHALL include a required nonempty string `owner` in the adapter state returned when launching detached work. Owner identity SHALL be stable across fresh adapter processes in the same execution environment. Participating host/container environments SHALL use distinct owner identities. Backend launch fields and other continuation fields SHALL remain preserved. Ownership SHALL NOT change runnable identity or cache identity. Saved object state without `owner` SHALL be unsupported; no compatibility fallback SHALL infer or claim ownership.
+
+#### Scenario: Launch identifies the environment performing the work
+- **WHEN** script or Docker starts detached work on environment A
+- **THEN** its returned adapter state contains owner A and the executor's backend launch fields
+
+#### Scenario: Fresh process retains the same ownership identity
+- **WHEN** another adapter process on environment A receives A-owned launch state
+- **THEN** it identifies itself as the same owner and can continue the existing work
+
+#### Scenario: Containerized script identifies its own environment
+- **WHEN** script launches inside a Docker container
+- **THEN** script returns the container environment's owner identity using the same launch contract as direct script execution
+- **AND** that identity is distinct from the host's Docker owner identity
+
+### Requirement: Ownership SHALL distinguish effective users on the same host
+
+The owner identifier SHALL have format `<effective UID>@<hostname>`, resolved in the execution environment where the executor runs. Different effective users on the same hostname SHALL have different owner identifiers. Username environment variables SHALL NOT determine identity. Ownerless or hostname-only saved state SHALL NOT receive a compatibility fallback.
+
+#### Scenario: Different users share a host
+- **WHEN** two executor processes run on the same hostname with different effective UIDs
+- **THEN** they produce different owner identifiers
+- **AND** neither can pass the other's local-resource ownership check
+
+#### Scenario: Username environment variables do not change ownership
+- **WHEN** the username environment changes without changing effective UID or hostname
+- **THEN** the owner identifier remains unchanged
+
+### Requirement: Local resource operations SHALL require matching ownership
+
+For saved object state, script and Docker SHALL check its required owner before any local resource inspection or teardown during invoke continuation, cleanup, or cancel. A different owner SHALL return status `retry`, unchanged object `adapter_state`, and null error without inspecting or modifying local processes, files, containers, or images. It SHALL NOT replace ownership, launch substitute work, report completed cleanup, or confirm cancellation. Matching ownership SHALL retain existing backend behavior. Null-state cleanup and cancellation SHALL retain their existing no-resource behavior.
+
+#### Scenario: Different machine polls shared state
+- **WHEN** environment B receives A-owned script or Docker state for an invoke continuation
+- **THEN** it returns retry with that state unchanged
+- **AND** it performs no local resource access
+
+#### Scenario: Different machine attempts published-result cleanup
+- **WHEN** environment B receives A-owned script or Docker state for cleanup
+- **THEN** it returns retry without deleting resources or reporting cleanup success
+- **AND** it preserves all continuation fields
+
+#### Scenario: Different machine attempts cancellation
+- **WHEN** environment B receives A-owned script or Docker state for cancel
+- **THEN** it returns retry without signaling a process or stopping/removing a container
+- **AND** it does not return cancelled
+
+#### Scenario: Owning environment continues local operations
+- **WHEN** environment A receives A-owned state for continuation, cleanup, or cancellation
+- **THEN** the existing backend operation proceeds against A's resources
+
+### Requirement: Transparent transports SHALL NOT pin ownership to their caller
+
+SSH SHALL forward operations and nested adapter state unchanged to its configured destination without adding a caller owner. Local ownership restrictions SHALL apply where script or Docker actually executes, not to the entire runnable chain. Batch SHALL NOT acquire a local-machine ownership restriction.
+
+#### Scenario: Two callers reach the same owning SSH destination
+- **WHEN** A and B call an SSH-wrapped Docker or script execution on C with C-owned saved state
+- **THEN** each forwards that state to C
+- **AND** the nested executor on C accepts its matching ownership
+
+#### Scenario: Batch continuation is independent of the original caller
+- **WHEN** another caller checks an existing Batch execution using its saved job state
+- **THEN** no script/Docker local-owner restriction is imposed on the Batch executor