Skip to content

build(maestro): prepare the private v2 factory and packed contracts - #4555

Open
thymikee wants to merge 13 commits into
0.22from
fix/c3-prep-atomic-layer-20261114
Open

thymikee wants to merge 13 commits into
0.22from
fix/c3-prep-atomic-layer-20261114

Conversation

@thymikee

@thymikee thymikee commented Nov 14, 2026 •

Copy link
Copy Markdown
Member

Summary

Prepare the v2 Maestro factory for #3377. Retain both Node-oracle and registered Vitest ownership for conformance inputs.

Unpublished candidate: 6c2ecce153d61b8416c9ee20e0fa58f153b4953d. 39 files / 851 gross lines above 0.22; 197 / 4,964 against default-main merge-base.

Validation

Independent Codex recheck found no actionable findings within the R1 repair and preservation interactions. The two-file repair survives all four rebases; eight range-diff entries match.

At 6c2ecce153d61b8416c9ee20e0fa58f153b4953d, pinned frozen install/build and full-repository format passed. Exact affected: 42 passed / 25 skipped, exactCommit=true, checkoutChanged=false; receipt 1732f0c549318f6f38201f7fe47b1ce862bbc6f6821c7eb6f6f46661a3e4d3a1.

All seven new-head canonical invocations passed once, serially, under one frozen ENV. Counts overlap; skips retain their CI/manual owners. Existing refs stayed unchanged; source/logical index matched before and after each gate. Physical-index captures remain separate, with within-head byte-change causes unproven. Initial/final snapshots cannot exclude transient edits.

The candidate remains unpublished; published head c3b54117 is unchanged and new-head hosted checks are unverified. Node22.13 packaging and earlier ENV/ref owner dispositions still block source publication. Both plugins remain private pending maintainer placeholders, trusted publishers and usable publication. Native ADR, live/current-client, performance and security remain open. No merge clearance.


Autofix with [code]smith
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.

View guided diff Turn on auto-fix

airowe and others added 9 commits November 14, 2026 09:13
…#4177)

* fix(daemon): refuse leased requests that name no session at admission

The CLI already requires an explicit session on a leased remote
connection, but a direct RPC or socket caller could still omit it and
land in the shared default session.

HTTP and socket intake now mark a missing or blank session on the
daemon-only request envelope. Admission refuses a marked request that
allocates a provider lease or carries a lease, with the existing
REMOTE_SESSION_REQUIRED reason, before anything is allocated or
dispatched. A provider named without a lease stays allowed, and an
explicit session name, including "default", counts as named.

Closes #4171

* fix(daemon): close the remaining unnamed lease paths at admission

agent_device.install_from_source did not record an omitted session, so an
unnamed install could reach the provider lease held by the default session.
A batch step also lost the marker, so a step carrying lease flags passed
admission.

Lease-exempt commands such as session_list now read only a lease they carry
themselves, so an unnamed inventory command still answers while the default
session holds a provider lease.

The refusal also names the session parameter for direct RPC callers, and the
ledger now digests the shared session helper and describes blank names for
released clients correctly.

* fix(daemon): keep session-held leases out of unnamed artifacts and queued requests

Only inventory and lease-lifecycle commands now ignore the lease on the
session they resolve. artifacts and events act through that session, so an
unnamed request for them is refused again.

Admission also repeats the check under the session lock, because an unnamed
request can wait behind an open that leaves a provider lease on the session.

* fix(daemon): refuse unnamed doctor and capabilities on a leased session

Both resolve the session's device, so an unnamed request could inspect a
device another caller leased. An explicit list now names the commands that
never read the session, and every other command stays refused.
release_materialized_paths joins that list, because it uses no session.

* fix(daemon): treat a blank session as the default one at intake

A blank session name was marked as unnamed but stayed its own session, so the marker
described a request that still ran somewhere else. HTTP and socket intake now both
resolve a missing or blank name to the default session. A mutation case holds the
marker in place, and the transport tests assert that the handler ran on that session.

* fix(daemon): refuse the Node client on a provider lease when it names no session

The Node client always sends the literal default session and reports the omission in
meta.sessionExplicit, so intake never marked it and an unnamed leases.allocate still
allocated a lease. One intake helper now decides this for the socket and every HTTP
builder, and lease RPC params carry the fact. The commands that ignore their session's
lease become a registry trait. Docs examples and in-repo clients on a provider lease
now name a session.

* fix(contracts): forward a session named in flags on the lease RPC

The lease RPC projection dropped flags.session and forwarded sessionExplicit false, so
a caller that named its session in flags was refused there but not on the command
method. The route now forwards the shared predicate's answer. Also cover the lease
method in the real-daemon test and document where each method reads the fact.

* refactor(kernel): home the session-naming predicate in the record module

The lease RPC builder needs the predicate, and importing it from the contracts hub made three entry surfaces evaluate more modules. The record module is already in those closures.

* docs(daemon): say batch steps also carry the session-omitted marker

* fix(daemon): keep a blank session literal at intake

Intake rewrote a blank session to default, so after main made each web
session its own device, an HTTP RPC open with session "" ran the default
browser instead of being refused with web_session_name_invalid. A missing
session still runs under default. A blank one keeps its literal and still
names no session, so a provider lease refuses it as before and the web
name check refuses it too.

Refs #4171

* fix(daemon): import the session naming check from kernel/record

Main's router now reports a named session that is missing, through
namesSessionExplicitly from kernel/contracts. This branch moved that
helper to kernel/record, so the merge left a dangling import.

Refs #4171

* chore(gates): reconcile admission checks with 0.22 owners

---------

Co-authored-by: Michał Pierzchała <thymikee@gmail.com>
…) (#4504)

* refactor(plugins): remove the version 1 provider plugin contract (#3759)

Drop the v1 loader adapter, the manifest-driven discovery and store branches, the
manifest credential and connection fallbacks, and the install-time provider
collision checks. A store package is discovered through its exports only, and
everything it declares comes from the object its factory returns. The registry
settles a duplicate provider id by first claim.

Remove the v1 entries and manifest declarations from TestMu AI and Revyl, and
document the migration to an AgentDevicePluginFactory in ./agent-device.

* refactor(plugins): keep entry resolution module-private after the v1 removal

discoverPluginEntry is the only caller of resolvePluginEntry, and the store's
version-selector check lost its second caller with the manifest branches, so
both become module-local. Drop the deleted v1 entries from the Fallow entry
list. Removes the dead-export findings the fallow audit raised at head.

* refactor(plugins): answer the review findings on the v1 removal

Point the traversal fixture at the file that exists outside the package, say the
entry contract as it is (root export, which is main without exports), move the
v1 manifest's connection to connection.capabilities in the migration note and
separate the incompatible_plugin and invalid_plugin cases, claim the built-in id
with a non-routing provider in the store test, and state what install checks.
* refactor(sdk): require explicit host dependencies in 0.22

* chore(gates): remove ambient SDK process entry waivers

* fix(sdk): preserve request overlays and archive working directories
#4528)

* test(maestro): colocate engine export tests before extraction

* test(cli): isolate Maestro suite forwarding from network reporting

* test(cli): restore isolated cwd for Maestro suite forwarding
Prepare the private factory, declaration chunks and artifact checks together with matching export, dependency and project-reference contracts. Keep the built-in consumer behavior until the migration layer. Omit the unused unshipped ManagedPlugin alias.
@github-actions

github-actions Bot commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Size Report

Metric Base Current Diff
Installed (including dependencies) 6.28 MB 6.31 MB +29.4 kB
Package (unpacked) 6.27 MB 6.30 MB +29.4 kB
Package (download) 1.90 MB 1.91 MB +9.2 kB

Startup median (7 runs, lower is better):

Scenario Base Current Diff
CLI --version 18.7 ms 18.9 ms +0.2 ms
CLI --help 38.5 ms 39.6 ms +1.1 ms

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

10 issues found across 29 files

You’re at about 92% of the monthly reviewed-line limit. You may want to disable incremental reviews to conserve quota. Reviews will continue until that limit is exceeded. If you need help avoiding interruptions, please contact contact@cubic.dev.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="scripts/check-affected/model.test.ts">

<violation number="1" location="scripts/check-affected/model.test.ts:562">
P3: This guard omits `packages/plugins/src/discovery.ts`, which `replayBackendOwnership` routes to both Maestro lanes. Add it to the list so the test covers every file the rule claims. The test also never asserts `failOpen === false`, so it would still pass if these paths fell back to the full set.</violation>
</file>

<file name="package.json">

<violation number="1" location="package.json:168">
P1: Appending `-- --pack-destination .tmp/release` to `check:package` now sends the flag to the last command in the `&&` chain, not to `check-package.ts`. The release tarball is then not written to `.tmp/release`, and the test runner gets an unexpected `--pack-destination` argument. Invoke `scripts/check-package.ts` directly with the flag in `release:prepare` instead, and keep the artifact test in `check:package`.</violation>

<violation number="2" location="package.json:168">
P2: `check:package` drops the TypeScript flag when the temp-dir wrapper starts the artifact test, so the new test fails on the supported Node 22.12–22.17 range while importing `@agent-device/host-kit/command`. Pass `--experimental-strip-types` through to the child invocation.</violation>
</file>

<file name="scripts/layering/package-boundaries-dev-dependencies.test.ts">

<violation number="1" location="scripts/layering/package-boundaries-dev-dependencies.test.ts:112">
P3: These two count-only assertions don't check which rule fires. Match the message as the neighboring tests do, so a regression that reports the wrong cause still fails.</violation>
</file>

<file name="packages/maestro/package.json">

<violation number="1" location="packages/maestro/package.json:7">
P3: This package is configured for public publishing (`publishConfig.access: public`) but has no `license` or `repository` field, unlike the sibling publishable packages. Add them now so the trusted-publisher and provenance setup can verify the source repository before the first publish.</violation>
</file>

<file name="scripts/gate/workflows.test.ts">

<violation number="1" location="scripts/gate/workflows.test.ts:76">
P2: This rewrite hides a gap: `verbatimScripts` never credits a script whose whole body is a compound command, even when a command repeats that body verbatim. The test now asserts `['verify']` for the `combined` body, which means `combined` is not credited for itself. Compare the whole command as well as its segments, and update this assertion to expect `['combined', 'verify']`. Otherwise keep the real `check:package` case covered.</violation>
</file>

<file name="packages/maestro/src/plugin.ts">

<violation number="1" location="packages/maestro/src/plugin.ts:19">
P3: This emits the same `png_worker_unavailable` phase as the daemon, but with `data` set to the raw reason object, so the key is `kind` instead of `reason`. Log consumers that read `data.reason` will miss these events. Pass `{ reason: reason.kind, detail: reason.detail }` to match the daemon.</violation>
</file>

<file name="scripts/layering/package-boundaries.test.ts">

<violation number="1" location="scripts/layering/package-boundaries.test.ts:678">
P3: This comment calls `./agent-device` a "source test facade", but it maps to `src/plugin.ts`, the plugin entry. The replacement also drops the earlier note on why `.` stays free of the replay plugin and the pointer to the eager-closure budget gate. Describe the source export accurately and keep the pointer to that gate.</violation>
</file>

<file name="scripts/check-affected/model.ts">

<violation number="1" location="scripts/check-affected/model.ts:265">
P3: The new `replayBackendOwnership` rule sits between the `workspacePackageOwnership` comment and the function it describes. Move the rule above that comment block so the comment stays attached to `workspacePackageOwnership`.</violation>

<violation number="2" location="scripts/check-affected/model.ts:266">
P2: The `packages/maestro/` prefix is not limited to source or TypeScript files. Maestro package config and `.mjs` test files that used to fail open to the full set now narrow to only the conformance and differential gates. Confirm these files still reach their build and typecheck gates, or limit the prefix to the paths that need the oracle.</violation>
</file>

Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic

Comment thread package.json
"check:production-exports": "fallow dead-code --config fallow-production-exports.json --production --unused-exports --fail-on-issues",
"check:bundle-owner-files": "node --experimental-strip-types scripts/check-bundle-owner-files.ts",
"check:package": "node --experimental-strip-types scripts/check-package.ts",
"check:package": "node --experimental-strip-types scripts/check-package.ts && node --experimental-strip-types scripts/node-test-tmpdir.ts --test packages/maestro/test/package-artifact.test.mjs",

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1: Appending -- --pack-destination .tmp/release to check:package now sends the flag to the last command in the && chain, not to check-package.ts. The release tarball is then not written to .tmp/release, and the test runner gets an unexpected --pack-destination argument. Invoke scripts/check-package.ts directly with the flag in release:prepare instead, and keep the artifact test in check:package.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At package.json, line 168:

<comment>Appending `-- --pack-destination .tmp/release` to `check:package` now sends the flag to the last command in the `&&` chain, not to `check-package.ts`. The release tarball is then not written to `.tmp/release`, and the test runner gets an unexpected `--pack-destination` argument. Invoke `scripts/check-package.ts` directly with the flag in `release:prepare` instead, and keep the artifact test in `check:package`.</comment>

<file context>
@@ -165,7 +165,7 @@
     "check:production-exports": "fallow dead-code --config fallow-production-exports.json --production --unused-exports --fail-on-issues",
     "check:bundle-owner-files": "node --experimental-strip-types scripts/check-bundle-owner-files.ts",
-    "check:package": "node --experimental-strip-types scripts/check-package.ts",
+    "check:package": "node --experimental-strip-types scripts/check-package.ts && node --experimental-strip-types scripts/node-test-tmpdir.ts --test packages/maestro/test/package-artifact.test.mjs",
     "check:command-docs": "vitest run --project unit-core test/repo-guards/command-doc-coverage.test.ts",
     "check:adr-citations": "vitest run --project unit-core test/repo-guards/adr-citations.test.ts",
</file context>

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Accepted; this duplicates the routing issue tracked in #4555 (comment). The local root-9f PREP retains artifact tests first and scripts/check-package.ts last, so forwarded --pack-destination reaches its owner. Current repair candidate is e018cbe6993cd7d522962f68e3ce0ad0a5ca91d1. The published c3b5411 head is unchanged; Node22.13 packaging and predecessor ENV-protocol disposition still block publication. Keeping this open until the fix is published.

Comment thread packages/plugins/src/replay-backend.ts Resolved
combined: 'node scripts/verify.ts && node scripts/other.ts',
};
assert.deepEqual(verbatimScripts(scripts.verify, scripts), ['verify']);
assert.deepEqual(verbatimScripts(scripts.combined, scripts), ['verify']);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: This rewrite hides a gap: verbatimScripts never credits a script whose whole body is a compound command, even when a command repeats that body verbatim. The test now asserts ['verify'] for the combined body, which means combined is not credited for itself. Compare the whole command as well as its segments, and update this assertion to expect ['combined', 'verify']. Otherwise keep the real check:package case covered.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At scripts/gate/workflows.test.ts, line 76:

<comment>This rewrite hides a gap: `verbatimScripts` never credits a script whose whole body is a compound command, even when a command repeats that body verbatim. The test now asserts `['verify']` for the `combined` body, which means `combined` is not credited for itself. Compare the whole command as well as its segments, and update this assertion to expect `['combined', 'verify']`. Otherwise keep the real `check:package` case covered.</comment>

<file context>
@@ -68,9 +68,13 @@ function planted(files: Record<string, string>): ReturnType<typeof loadLanes> {
+    combined: 'node scripts/verify.ts && node scripts/other.ts',
+  };
+  assert.deepEqual(verbatimScripts(scripts.verify, scripts), ['verify']);
+  assert.deepEqual(verbatimScripts(scripts.combined, scripts), ['verify']);
+  assert.deepEqual(verbatimScripts('node scripts/something-else.ts', scripts), []);
 });
</file context>

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Accepted. Local PREP repair 30103464a80fe14135ac8956894a4c2b408b4ec3 compares the normalized whole command as well as its segments. The existing combined-body case now requires both verify and combined in declaration order. That unchanged command failed the strengthened test before the production fix and passed afterward. The real package script and existing gate ownership remain intact. Included in candidate e018cbe6993cd7d522962f68e3ce0ad0a5ca91d1; independent review/exact admission and publication remain pending, so this thread stays open.

Comment thread packages/maestro/src/plugin.ts Resolved
};
assert.deepEqual(violations(staged, 'packages/owner/src/thing.ts'), []);
assert.equal(
violations({ ...staged, devDependencies: {} }, 'packages/owner/src/thing.ts').length,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: These two count-only assertions don't check which rule fires. Match the message as the neighboring tests do, so a regression that reports the wrong cause still fails.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At scripts/layering/package-boundaries-dev-dependencies.test.ts, line 112:

<comment>These two count-only assertions don't check which rule fires. Match the message as the neighboring tests do, so a regression that reports the wrong cause still fails.</comment>

<file context>
@@ -101,3 +101,16 @@ test('a published package keeps its siblings in devDependencies for every file',
+  };
+  assert.deepEqual(violations(staged, 'packages/owner/src/thing.ts'), []);
+  assert.equal(
+    violations({ ...staged, devDependencies: {} }, 'packages/owner/src/thing.ts').length,
+    1,
+  );
</file context>

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Accepted. The local repair retains the count assertions and also matches the independent expected diagnostics: an undeclared sibling reports without declaring, while a private dev-only production import reports declare it in dependencies. The complete two-file layering-focused run passes. This is in unpublished candidate e018cbe6993cd7d522962f68e3ce0ad0a5ca91d1; keeping the thread open until publication.

"@agent-device/provision-kit": "workspace:*",
"@agent-device/selectors": "workspace:*"
},
"description": "Optional Maestro compatibility engine plugin for agent-device.",

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: This package is configured for public publishing (publishConfig.access: public) but has no license or repository field, unlike the sibling publishable packages. Add them now so the trusted-publisher and provenance setup can verify the source repository before the first publish.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At packages/maestro/package.json, line 7:

<comment>This package is configured for public publishing (`publishConfig.access: public`) but has no `license` or `repository` field, unlike the sibling publishable packages. Add them now so the trusted-publisher and provenance setup can verify the source repository before the first publish.</comment>

<file context>
@@ -4,16 +4,7 @@
-    "@agent-device/provision-kit": "workspace:*",
-    "@agent-device/selectors": "workspace:*"
-  },
+  "description": "Optional Maestro compatibility engine plugin for agent-device.",
   "exports": {
     ".": {
</file context>
Suggested change
"description": "Optional Maestro compatibility engine plugin for agent-device.",
"description": "Optional Maestro compatibility engine plugin for agent-device.",
"license": "MIT",
"repository": {
"type": "git",
"url": "git+https://github.com/callstack/agent-device.git",
"directory": "packages/maestro"
},

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Accepted. Local commit e018cbe6993cd7d522962f68e3ce0ad0a5ca91d1 adds license MIT and repository git+https://github.com/callstack/agent-device.git with directory packages/maestro. private:true and the publication/export contract remain unchanged. This metadata does not substitute for the maintainer-owned non-latest placeholder, trusted-publisher configuration or usable publication, which remain required before merge. Full repository formatting passed; independent/exact admission and publication are pending.

import('@agent-device/capture-kit/png-worker-client'),
]);
releasePngWorker ??= retainPngWorker((reason) =>
host.emitDiagnostic({ level: 'warn', phase: 'png_worker_unavailable', data: reason }),

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: This emits the same png_worker_unavailable phase as the daemon, but with data set to the raw reason object, so the key is kind instead of reason. Log consumers that read data.reason will miss these events. Pass { reason: reason.kind, detail: reason.detail } to match the daemon.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At packages/maestro/src/plugin.ts, line 19:

<comment>This emits the same `png_worker_unavailable` phase as the daemon, but with `data` set to the raw reason object, so the key is `kind` instead of `reason`. Log consumers that read `data.reason` will miss these events. Pass `{ reason: reason.kind, detail: reason.detail }` to match the daemon.</comment>

<file context>
@@ -0,0 +1,32 @@
+              import('@agent-device/capture-kit/png-worker-client'),
+            ]);
+            releasePngWorker ??= retainPngWorker((reason) =>
+              host.emitDiagnostic({ level: 'warn', phase: 'png_worker_unavailable', data: reason }),
+            );
+            return await maestroReplayBackendPlugin.create(host);
</file context>

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Accepted. Local repair 30103464a80fe14135ac8956894a4c2b408b4ec3 projects the existing typed worker reason into data.reason and data.detail, matching daemon-runtime.ts, rather than exposing data.kind for the same phase. The existing worker-retention/diagnostic/disposal test now asserts that outward shape: it fails on the old projection and passes with the fix. No diagnostic text matching or new worker lifecycle owner was added. Candidate e018cbe6993cd7d522962f68e3ce0ad0a5ca91d1 remains unpublished and awaits independent/exact admission.

// Locks the export surface: `.` (the engine), the replay backend plugin (#3377) with its
// engine-free declaration, and the runScript HTTP helper. The eager-closure budget gate
// (scripts/__tests__/eager-closure-budgets.test.ts) is what keeps the plugin off `.`.
// Source test facades stay private to the workspace; package smoke pins the published host entry.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: This comment calls ./agent-device a "source test facade", but it maps to src/plugin.ts, the plugin entry. The replacement also drops the earlier note on why . stays free of the replay plugin and the pointer to the eager-closure budget gate. Describe the source export accurately and keep the pointer to that gate.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At scripts/layering/package-boundaries.test.ts, line 678:

<comment>This comment calls `./agent-device` a "source test facade", but it maps to `src/plugin.ts`, the plugin entry. The replacement also drops the earlier note on why `.` stays free of the replay plugin and the pointer to the eager-closure budget gate. Describe the source export accurately and keep the pointer to that gate.</comment>

<file context>
@@ -675,11 +675,10 @@ test('the real tree parses, declares, and passes R11', () => {
-  // Locks the export surface: `.` (the engine), the replay backend plugin (#3377) with its
-  // engine-free declaration, and the runScript HTTP helper. The eager-closure budget gate
-  // (scripts/__tests__/eager-closure-budgets.test.ts) is what keeps the plugin off `.`.
+  // Source test facades stay private to the workspace; package smoke pins the published host entry.
   assert.deepEqual([...maestroPackage.exportTargets.keys()].sort(), [
     '@agent-device/maestro',
</file context>
Suggested change
// Source test facades stay private to the workspace; package smoke pins the published host entry.
// `./agent-device` maps to the plugin source for workspace use; publishConfig.exports pins the published host entry. The eager-closure budget gate (scripts/__tests__/eager-closure-budgets.test.ts) keeps the replay plugin off `.`.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Accepted that the blanket source-test-facade comment was inaccurate for ./agent-device. The local repair removes that redundant comment; the adjacent exact export-target assertion and packed host-entry tests remain. It does not restore a pointer to an old source layout: the eager-closure guard remains enforced by its owning test. Included in unpublished e018cbe6993cd7d522962f68e3ce0ad0a5ca91d1, with independent/exact admission pending.

// claimed its resolver could not follow workspace specifiers, which stopped
// being true (it resolves @agent-device/* through each exports map), so an
// extraction into packages/ no longer takes its own dead code out of scope.
const replayBackendOwnership: OwnershipRule = ({ file }) =>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: The new replayBackendOwnership rule sits between the workspacePackageOwnership comment and the function it describes. Move the rule above that comment block so the comment stays attached to workspacePackageOwnership.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At scripts/check-affected/model.ts, line 265:

<comment>The new `replayBackendOwnership` rule sits between the `workspacePackageOwnership` comment and the function it describes. Move the rule above that comment block so the comment stays attached to `workspacePackageOwnership`.</comment>

<file context>
@@ -262,6 +262,26 @@ const vitestRelatedOwnership: OwnershipRule = ({ file, isTs, underSrc, underTest
 // claimed its resolver could not follow workspace specifiers, which stopped
 // being true (it resolves @agent-device/* through each exports map), so an
 // extraction into packages/ no longer takes its own dead code out of scope.
+const replayBackendOwnership: OwnershipRule = ({ file }) =>
+  file.startsWith('packages/maestro/') ||
+  file.startsWith('packages/replay-port/') ||
</file context>

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Accepted. Local repair 30103464a80fe14135ac8956894a4c2b408b4ec3 moves the unchanged workspace-package ownership comment immediately above workspacePackageOwnership. The replay rule no longer separates that comment from its owner. Included in unpublished e018cbe6993cd7d522962f68e3ce0ad0a5ca91d1; keeping this open until publication.

@apex-sentinel-staging

apex-sentinel-staging Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

Apex Sentinel · 🟠 Request changes

Since the last review: 2 new · 0 still open · 0 no longer raised

2 finding(s): 1 major, 1 minor.

Required fixes

  • check:package's new && suffix swallows release:prepare's --pack-destination flag

🟠 Major (1)

Where Finding
package.json:168 🆕 check:package's new && suffix swallows release:prepare's --pack-destination flag

🟡 Minor (1)

Where Finding
package.json:168 🆕 New package-artifact test's .ts host-kit import lacks forwarded --experimental-strip-types
Not in the reviewers' prompt (1 file)
  • pnpm-lock.yaml: generated or a lockfile, so its lines were left out

1 finding below minor hidden (user_settings.min_severity).

Reviewed with this repository's own Sentinel configuration (d78be6c88715).

💬 Talking to Sentinel

In a finding's thread, reply with:

Command What it does
@apex-sentinel-staging note <context> Adds context; Sentinel re-checks the cited code
@apex-sentinel-staging pivot <why> Says the finding is wrong; Sentinel re-checks the cited code
@apex-sentinel-staging like Marks the finding as useful
@apex-sentinel-staging dislike <why> Marks it as not useful, so it is not raised again

On this conversation, comment @apex-sentinel-staging review to run a full review once again.

Earlier reviews

Review of b057f879 · 14.11.2026 18:26 UTC

Apex Sentinel · ✅ Approve

Since the last review: 0 new · 0 still open · 1 no longer raised

No open findings.

Not in the reviewers' prompt (1 file)
  • pnpm-lock.yaml: generated or a lockfile, so its lines were left out

1 finding below minor hidden (user_settings.min_severity).

Reviewed with this repository's own Sentinel configuration (d78be6c88715).

Review of feb7c25e · 14.11.2026 17:45 UTC

Apex Sentinel · ✅ Approve

1 finding(s): 1 minor.

🟡 Minor (1)

Where Finding
package.json:168 check:package's new maestro artifact test cannot load its .ts host-kit import (no forwarded --experimental-strip-types)
Not in the reviewers' prompt (1 file)
  • pnpm-lock.yaml: generated or a lockfile, so its lines were left out

1 finding below minor hidden (user_settings.min_severity).

Reviewed with this repository's own Sentinel configuration (d78be6c88715).

@apex-sentinel-staging apex-sentinel-staging Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apex Sentinel: 1 new finding on feb7c25. The verdict and the full list are in the summary comment.

Comment thread package.json
"check:production-exports": "fallow dead-code --config fallow-production-exports.json --production --unused-exports --fail-on-issues",
"check:bundle-owner-files": "node --experimental-strip-types scripts/check-bundle-owner-files.ts",
"check:package": "node --experimental-strip-types scripts/check-package.ts",
"check:package": "node --experimental-strip-types scripts/check-package.ts && node --experimental-strip-types scripts/node-test-tmpdir.ts --test packages/maestro/test/package-artifact.test.mjs",

@apex-sentinel-staging apex-sentinel-staging Bot Nov 14, 2026 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🆕 🟡 Minor · New package-artifact test's .ts host-kit import lacks forwarded --experimental-strip-types

check:package invokes node-test-tmpdir.ts without --experimental-strip-types as its first argument, so the child test process gets no flag. package-test-support.mjs imports @agent-device/host-kit/command which resolves to .ts source, so the child fails with ERR_UNKNOWN_FILE_EXTENSION. Every other node-test-tmpdir invocation in package.json forwards --experimental-strip-types first.

Suggested change
"check:package": "node --experimental-strip-types scripts/check-package.ts && node --experimental-strip-types scripts/node-test-tmpdir.ts --test packages/maestro/test/package-artifact.test.mjs",
"check:package": "node --experimental-strip-types scripts/check-package.ts && node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test packages/maestro/test/package-artifact.test.mjs",
Details

persona: senior-developer, javascript

Useful? Reply @apex-sentinel-staging like, or @apex-sentinel-staging dislike <why> if it is not.

Reply @apex-sentinel-staging note ... to add context, or @apex-sentinel-staging pivot ... if it is wrong — I will re-check the cited code.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Accepted after rechecking the supported development floor. My earlier dismissal based only on Node 22.12 being outside the repository's Node >=22.13 development contract was incomplete: Node 22.13–22.17 still requires the child flag. Type stripping became enabled by default in Node 22.18; the 22.13 documentation specifies --experimental-strip-types.

The local correction at PREP 15036137c69b9601d933bb50fba24e089aa53e35 explicitly forwards that flag after node-test-tmpdir.ts, while also correcting the release-argument routing reported in the other thread. All existing artifact/smoke test paths are preserved upstack. This is committed locally, not published or newly validated. An actual supported-floor check is still owed; current Node 26 results are not floor coverage. Keeping the thread open until review/validation/publication clear.

@thymikee

Copy link
Copy Markdown
Member Author

The code in feb7c25 has no merge-stopping defect of its own, but the open blocking thread on check:package still has to be fixed. CI is red on the Coverage changed-line gate: 1 of 8 changed executable lines is covered, and the uncovered lines are all in packages/maestro/src/plugin.ts, so this PR causes it.

Before merge, please keep check:package a single command and run the Maestro artifact test as its own gate step or a separate check:package-maestro script. Then add a unit test that loads the factory, calls maestroPlugin().setup().replayBackend.create(stubHost), asserts the backend id is maestro, and checks that dispose() releases the worker hold. That test also covers the changed lines for the gate. There are no conflicts.

Not blocking, and you can take or leave these: DiagnosticLevel and DiagnosticEventInput are now declared in contracts and again in host-kit, so the diagnostic-input shape has two owners that agree only structurally; ReplayEnginePlugin in replay-backend.ts hard-codes apiVersion: 2 and adds a kind field instead of extending the contract that uses PROVIDER_PLUGIN_API_VERSION; and the factory in plugin.ts is only exercised by the packed artifact test, which never imports dist/agent-device.mjs.

Could this slice be simpler with two ownership moves and one script fix? (1) Keep the diagnostic types in contracts and have host-kit re-export them. (2) Declare ReplayEnginePlugin in plugins/src/contract.ts with PROVIDER_PLUGIN_API_VERSION, so the consumer PR extends one validator. (3) Split the Maestro artifact test out of check:package, which keeps release:prepare and smoke-macos flag forwarding and the workflows test working. Could the ReplayBackend/ReplayBackendHost public re-export also wait until an external engine needs it? Nothing else has to change first.

The open threads still apply: the blocking thread on release:prepare flag forwarding, and the threads on artifact test, backend typing, workflows crediting, dispose race, SDK re-export, check-affected narrowing and strip-types on Node 22. The second strip-types thread covers the same mechanism. Six lower-priority threads also still apply. No open thread is out of date.

I did not run pnpm check:package or the release:prepare chain. That thread is confirmed from reading package.json, node-test-tmpdir.ts and check-package.ts. I also did not verify the local gate receipt or the Size check numbers. I did not inspect every ownership rule for packages/maestro/package.json.

@thymikee

Copy link
Copy Markdown
Member Author

One problem from the earlier review (feb7c25) is still open at b057f87. The new plugin.test.ts clears the failing Coverage changed-line check, and CI is green with 21 checks passing. There are no conflicts.

check:package is still a compound && script (package.json:168). pnpm appends forwarded flags to the end of the script string. So pnpm check:package -- --pack-destination .tmp/release (package.json:124) and pnpm check:package -- --verify-snapshot-bridge-preparation (smoke-macos action.yml:100) send the flag to node-test-tmpdir.ts, which passes it on to node --test. scripts/check-package.ts never sees it. It packs the root tarball into its temp dir and skips the snapshot-bridge check. Then release-workspace.mjs pack (lines 49-62) runs tar -xOf .tmp/release/agent-device-<version>.tgz on a file that does not exist. The Release workflow (pnpm release:prepare) would fail on a 0.22 release, and the macOS smoke would stop checking snapshot-bridge preparation without any error. Green CI does not cover this, because the CI package gate passes no forwarded flags. The rule: every script run as pnpm <script> -- <flags> must be one command whose last argv is the program that owns those flags. Please restore check:package to node --experimental-strip-types scripts/check-package.ts and run the Maestro artifact test as its own script and gate step. Then restore the /scripts\/check-package\.ts$/ guard and the verbatimScripts test on check:package. grep for pnpm check:package -- finds both callers. To validate, run pnpm release:prepare and show that .tmp/release/agent-device-<version>.tgz exists and the snapshot-bridge check runs.

Not blocking, and you can take or leave it: plugin.test.ts only covers the source plugin.ts, and it awaits dispose after both creates resolve, so the dispose-before-create-resolves path (plugin.ts:14-24) has no test. The packed dist/agent-device.mjs is also only checked for existence (package-artifact.test.mjs:26-32). Importing it and asserting default().backend === 'maestro' would close that gap.

The inline thread on the compound script still applies. So do the threads on the existence-only artifact test, backend id typing, the planted workflow test, the dispose race, the unused plugin exports, the broad Maestro lane match and the missing strip-types flag. Six lower-priority threads also still apply. The withdrawn thread on the same script describes the same problem and the code has not changed, so please leave it open.

I did not run pnpm check:package, release:prepare or the new plugin.test.ts. The finding above comes from reading package.json, node-test-tmpdir.ts, check-package.ts and release-workspace.mjs. I did not open the hosted Coverage log, and I did not check the affected-run receipt or archive hashes in the PR body.

Before merge, please split the Maestro artifact test out of check:package so flag forwarding reaches scripts/check-package.ts again.

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 15 files (changes from recent commits).

You’re at about 93% of the monthly reviewed-line limit. You may want to disable incremental reviews to conserve quota. Reviews will continue until that limit is exceeded. If you need help avoiding interruptions, please contact contact@cubic.dev.

Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic

Comment thread .fallowrc.json Resolved

@apex-sentinel-staging apex-sentinel-staging Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apex Sentinel: 1 new finding on c3b5411. The verdict and the full list are in the summary comment.

Comment thread package.json
"check:production-exports": "fallow dead-code --config fallow-production-exports.json --production --unused-exports --fail-on-issues",
"check:bundle-owner-files": "node --experimental-strip-types scripts/check-bundle-owner-files.ts",
"check:package": "node --experimental-strip-types scripts/check-package.ts",
"check:package": "node --experimental-strip-types scripts/check-package.ts && node --experimental-strip-types scripts/node-test-tmpdir.ts --test packages/maestro/test/package-artifact.test.mjs",

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🆕 🟠 Major · check:package's new && suffix swallows release:prepare's --pack-destination flag

pnpm release:prepare forwards --pack-destination .tmp/release to the end of the script string, so with the new && suffix it lands on the maestro test command instead of scripts/check-package.ts—the test runner fails on the unknown option and check-package.ts silently loses the pack-destination, so the release flow no longer retains the verified tarball.

Suggested change

Keep check:package a single command that takes forwarded args (e.g. move the maestro artifact test into its own script or have check-package.ts spawn it after its own probe), so pnpm check:package -- --pack-destination ... still reaches scripts/check-package.ts.

Details

persona: senior-developer

Useful? Reply @apex-sentinel-staging like, or @apex-sentinel-staging dislike <why> if it is not.

Reply @apex-sentinel-staging note ... to add context, or @apex-sentinel-staging pivot ... if it is wrong — I will re-check the cited code.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Accepted. The appended release arguments reach the final command in the script, so the current order deprives scripts/check-package.ts of --pack-destination.

A local correction at PREP 15036137c69b9601d933bb50fba24e089aa53e35 runs the artifact tests first and keeps the core package probe last. This preserves the existing package gate and its forwarded arguments without adding a wrapper or removing tests. All consumer/TOP test-file suffixes are retained in the restacked local family, ending at 3c7f1cc9fa9ce359df63da6ba5d1a34a3e55287d.

A standalone argument-routing probe using pinned pnpm 11.17.0 and the actual PREP/TOP script strings confirms old routing fails the ownership condition and corrected routing passes. Both raw pnpm commands exit 0 because the fixture only records argv; this is not an actual release, retained-tarball test or canonical-gate pass. Actual package-destination verification, independent source review and new-head validation remain owed. Keeping this thread open until the correction is admitted and published. No release/publish/CI rerun was triggered.

@thymikee

Copy link
Copy Markdown
Member Author

I re-reviewed c3b5411. One defect from the earlier review is still open; the other findings there are fixed.

check:package in package.json:168 is still a compound && script, and pnpm appends forwarded args to the last command. pnpm release:prepare runs pnpm check:package -- --pack-destination .tmp/release, so check-package.ts packs into its own temp dir and never writes the root tarball. scripts/release-workspace.mjs:56-61 skips packing the root and then reads that missing tarball, so release:prepare and prepack fail. The same problem hits .github/actions/smoke-macos/action.yml:100: --verify-snapshot-bridge-preparation never reaches check-package.ts, so the macOS snapshot-bridge proof silently stops running. The rule: every forwarded pnpm check:package -- <flag> must reach scripts/check-package.ts. Please make check:package the single check-package.ts command again, and run the Maestro artifact test as its own script or gate step (for example check:package:maestro, called from the CI package step and package:npm), with --experimental-strip-types. That also restores the single-entry match at npm-package-scripts.test.ts:101 and the original assertion in workflows.test.ts.

Not blocking, take or leave: the Maestro bundle still carries its own copy of the private-evidence store, and daemon-runtime-port-snapshot-source.ts:40 copies the clickability fact into it, so one fact has two stores and a future bundled read of another private fact on host objects would fail open; letting runtime-clickability take the host reader directly, or asserting the bundle reads private evidence only through ReplayBackendHost, would close that.

On the open inline threads: the one on package.json:168 args still stands as the defect above, with its duplicate. These still apply too: strip-types flag (and its duplicate), replay backend id type, workflows assertion, dispose race, and check-affected ownership. Three lower-priority threads still apply as well. These do not apply and can be resolved: packed harnesses do load the factory, ReplayEngineSetup is reachable from the public entry, package is still private, so license can wait, and Fallow entries, already answered.

All 20 build and test jobs pass, and the CI package step runs the script with no forwarded flags, so it does not cover the release or smoke-macos route. The remaining non-passing check sits on the same package.json:168 line. There are no conflicts. I did not run check:package, release:prepare or the packed harnesses; the release failure is traced from the scripts. Before merge, the package.json:168 change needs to land, and a release:prepare run should reach a root tarball in .tmp/release.

@thymikee

Copy link
Copy Markdown
Member Author

This branch now conflicts with main at c3b5411. Please rebase onto main and push along with the fixes from the earlier review, and I will re-check the new head.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants