@intx/hub-sessions 0.2.2 → 0.3.0

package/dist/hub-session-orchestrator.js

@@ -11,12 +11,11 @@
 // with a small stub and an isolated emitter.
 import { eq } from "drizzle-orm";
 import { type } from "arktype";
-import { agentInstance, workflowDeployment } from "@intx/db/schema";
+import { workflowRun } from "@intx/db/schema";
 import { parseMailToEmail } from "@intx/mime";
 import { parseInferenceEvent } from "@intx/types/runtime";
 import { getLogger } from "@intx/log";
-import { isWorkflowDerivedAddress } from "@intx/workflow-deploy";
-import { findInstance, parseAgentId, requireInstance, } from "./hub-session-lookups.js";
+import { parseAgentId } from "./hub-session-lookups.js";
 const log = getLogger(["hub", "orchestrator"]);
 export function createHubSessionOrchestrator(deps) {
     const { events, router, db, eventCollectors, agentRepoStore } = deps;
@@ -45,55 +44,21 @@ export function createHubSessionOrchestrator(deps) {
             recipients: recipients.join(", "),
         });
     }));
-    unsubscribers.push(events.on("agent.deploy.ack", async ({ agentAddress, publicKey }) => {
-        // Workflow-derived addresses (the deployment-level
-        // `ins_<deploymentId>@<domain>` and the per-step
-        // `ins_<deploymentId>-<stepId>@<domain>`) have no agent_instance row;
-        // their public key lives on the workflow_deployment projection row,
-        // keyed by address. Persist it there so the reconnect ownership
-        // challenge can verify the deployment address. Only the
-        // deployment-level address has a row, so a stray per-step ack updates
-        // nothing. (This was previously a no-op, which is what left
-        // workflow-deployment addresses un-verifiable on reconnect.)
-        if (isWorkflowDerivedAddress(agentAddress)) {
-            await db
-                .update(workflowDeployment)
-                .set({ publicKey })
-                .where(eq(workflowDeployment.address, agentAddress));
+    unsubscribers.push(events.on("agent.deploy.ack", async (event) => {
+        const { agentAddress, publicKey, allocated } = event;
+        // Exclusive initialization publishes its key only after every deploy
+        // and asset pack succeeds under the allocation generation fence.
+        if (allocated !== undefined)
             return;
-        }
-        // A launched agent has an agent_instance row; a missing one is a bug
-        // to surface, not to drop silently.
-        const instance = await findInstance(db, agentAddress);
-        if (instance === undefined) {
-            throw new Error(`No active instance found for deploy ack on address "${agentAddress}"`);
-        }
+        // Every deploy address names a workflow run whose public key lives on its
+        // single self-anchored workflow_run row, keyed by address. Persist it
+        // there so the reconnect ownership challenge can verify the address off
+        // the same row `lookupPublicKey` reads. Only the deployment-level address
+        // owns a row, so a stray per-step ack updates nothing.
         await db
-            .update(agentInstance)
+            .update(workflowRun)
             .set({ publicKey })
-            .where(eq(agentInstance.id, instance.id));
-    }));
-    unsubscribers.push(events.on("agent.reconnected", async ({ agentAddress }) => {
-        const instance = await requireInstance(db, agentAddress);
-        if (!instance.sessionId) {
-            throw new Error(`Agent "${agentAddress}" reconnected but has no active session`);
-        }
-        const sessionId = instance.sessionId;
-        // A supervised deployment carries its grants and sources in the
-        // deploy pack and refreshes them over the supervisor's IPC
-        // credentials snapshot at spawn and recycle, so reconnect does not
-        // re-push them over the wire.
-        const now = new Date();
-        if (instance.status !== "running") {
-            await db
-                .update(agentInstance)
-                .set({ status: "running", updatedAt: now })
-                .where(eq(agentInstance.id, instance.id));
-        }
-        if (!eventCollectors.has(agentAddress)) {
-            eventCollectors.create(agentAddress, instance.tenantId, sessionId, instance.id);
-            log.info("Restored event collector for reconnected agent {agentAddress}", { agentAddress });
-        }
+            .where(eq(workflowRun.address, agentAddress));
     }));
     unsubscribers.push(events.on("deploy.ref.stale", async ({ agentAddress }) => {
         const agentId = parseAgentId(agentAddress);

package/dist/index.d.ts

@@ -1,18 +1,27 @@
 export { createAgentRepoStore, type AgentRepoStore, type DeployContent, } from "./agent-repo.js";
-export { createSessionService, SessionLaunchError, bridgeOrchestratorDeployContent, type SessionService, type DeployWorkflowDefinitionParams, type DeployWorkflowDefinitionResult, } from "./session-service.js";
+export { createSessionService, SessionLaunchError, bridgeOrchestratorDeployContent, deployCodeSourcedWorkflow, type SessionService, type DeployWorkflowDefinitionResult, type DeployWorkflowFromSourceParams, type DeployPreparedCodeSourcedWorkflowParams, type InstallAndApproveWorkflowSourceParams, type PreparedWorkflowDeployer, type DeployCodeSourcedWorkflowArgs, } from "./session-service.js";
+export { installAndApproveWorkflowDefinition, createDbFrozenApprovalWriter, type InstallAndApproveArgs, type InstallAndApproveResult, type ProbeGateResult, type ProbeApprovalPolicy, type ApproveProbedGrants, } from "./workflow-probe-gate.js";
+export { committedReadsToSourceTree } from "./committed-source-tree.js";
+export type { SourceTreeReads } from "./workflow-source-closure.js";
 export type { WorkflowDefinition } from "@intx/workflow/definition";
 export { createEventCollectorRegistry, type EventCollectorRegistry, } from "./event-collector-registry.js";
-export { createSidecarRouter, type SidecarRouter, type SidecarRouterConfig, type SidecarAuthIdentity, type SidecarAuthenticator, createSidecarTokenAuthenticator, type CreateSidecarTokenAuthenticatorDeps, type WsHandle, createSidecarEmitter, type SidecarEventEmitter, type SidecarEventMap, type SidecarEventType, type SidecarEventListener, type SidecarLookups, type SidecarMailPersistedPayload, type SidecarMailPersistedRow, } from "./ws/index.js";
-export { createHubSessionLookups, parseAgentId, type HubSessionLookupsDeps, } from "./hub-session-lookups.js";
+export { createSidecarRouter, type SidecarRouter, type SidecarRouterConfig, type SidecarAuthIdentity, type SidecarAuthenticator, type AllocatedSidecarTarget, type SidecarAllocationRouter, createSidecarCredentialResolver, createSidecarTokenAuthenticator, type CreateSidecarTokenAuthenticatorDeps, type WsHandle, createSidecarEmitter, type SidecarEventEmitter, type SidecarEventMap, type SidecarEventType, type SidecarEventListener, type SidecarLookups, type SidecarMailPersistedPayload, type SidecarMailPersistedRow, type MailTriggeredRunGrantsResult, type WorkflowRunPackSource, } from "./ws/index.js";
+export { createHubSessionLookups, findRoutableById, parseAgentId, resolveRoutableAddress, resolveRunIdForSession, resolveRunSessionId, runRowToRoutableRecord, type HubSessionLookupsDeps, type RoutableEndpoint, type RoutableRecord, } from "./hub-session-lookups.js";
 export { createHubSessionOrchestrator, type HubSessionOrchestrator, type HubSessionOrchestratorDeps, type HubSessionRouterFacade, } from "./hub-session-orchestrator.js";
 export { pushSourceUpdates, pushSourceUpdatesSubtree } from "./credential-push.js";
+export { createSidecarPluginRegistry, createSidecarAllocationReconciler, resolveEffectiveSidecarPlacement, type CreateSidecarPluginRegistryOpts, type DestroySidecarRequest, type DestroySidecarResult, type EnsureSidecarRequest, type EnsureSidecarResult, type ResolveEffectiveSidecarPlacementOpts, type SidecarCredentialIdentity, type SidecarCredentialResolver, type SidecarOperationFailure, type SidecarPluginRegistry, type SidecarProvisioner, type SidecarAllocationReconciler, type SidecarAllocationReconcilerDeps, } from "./sidecar-allocation/index.js";
+export { ensureWorkflowDefinitionForAsset } from "./workflow-definition-ensure.js";
+export { workflowSourceAssetMountPath } from "./workflow-closure-resolution.js";
+export { createWorkflowAllocationService, ExclusiveWorkflowPlacementError, resolveWorkflowSidecarPlacement, type PrepareExclusiveWorkflowDeploymentArgs, type PreparedExclusiveWorkflowDeployment, type WorkflowAllocationService, type WorkflowAllocationServiceDeps, } from "./workflow-allocation-service.js";
+export { createWorkflowDispatchService, type WorkflowDispatchAcknowledgement, type WorkflowDispatchService, type WorkflowDispatchServiceDeps, } from "./workflow-dispatch-service.js";
+export { listAcceptedWorkflowDispatches, listConsumedWorkflowDispatches, listReceivedWorkflowSignals, type AcceptedWorkflowDispatch, type ConsumedWorkflowDispatch, type ReceivedWorkflowSignal, } from "./workflow-dispatch-settlement.js";
 export { skillKindHandler, skillAuthorize, skillFrontmatterSchema, getSkillIndex, type SkillIndexEntry, type SkillFrontmatter, type SkillPrincipal, type SkillHubPrincipal, type SkillSidecarPrincipal, } from "./skill-kind.js";
 export { packageRegistryKindHandler, packageRegistryAuthorize, asTarballEntry, validateTarballPackageJSON, TARBALLS_PREFIX, TARBALL_FILENAME_PATTERN, REGISTRY_INDEX_PATH, WORKSPACE_BUILTINS_REGISTRY, } from "./package-registry-kind.js";
-export { workflowKindHandler, workflowAuthorize, workflowDefinitionEnvelopeSchema, WORKFLOW_JSON_PATH, CAPABILITY_DECLARATIONS_JSON_PATH, WORKFLOW_GITIGNORE_PATH, type WorkflowPrincipal, type WorkflowHubPrincipal, type WorkflowSidecarPrincipal, } from "./workflow-kind.js";
-export { workflowRunKindHandler, workflowRunAuthorize, enqueueInbox, dequeueToProcessing, readProcessingEntry, markConsumed, readOwnedMessageIds, replayProcessingToInbox, WORKFLOW_RUN_GITIGNORE_PATH, WORKFLOW_RUN_RUNS_PREFIX, WORKFLOW_RUN_EVENTS_DIR, WORKFLOW_RUN_AGENT_STATE_PREFIX, WORKFLOW_RUN_ADDRESSES_PREFIX, WORKFLOW_RUN_CONTROL_PREFIX, WORKFLOW_RUN_INBOX_DIR, WORKFLOW_RUN_PROCESSING_DIR, WORKFLOW_RUN_CONSUMED_DIR, WORKFLOW_RUN_WATERMARK_FILE, DEFAULT_CONSUMED_RETENTION_MS, type ClaimCheckEnvelope, type ConsumedEnvelope, type EnqueueInboxArgs, type EnqueueInboxResult, type DequeueToProcessingResult, type ReadProcessingEntryResult, type MarkConsumedArgs, type MarkConsumedResult, type ReplayProcessingToInboxOpts, type ReplayProcessingToInboxResult, type WorkflowRunPrincipal, type WorkflowRunHubPrincipal, type WorkflowRunSidecarPrincipal, type WorkflowRunWorkflowProcessPrincipal, type WorkflowRunSupervisorPrincipal, } from "./workflow-run-kind.js";
-export { createAssetService, AssetServiceError, DEFAULT_ASSET_REF, type AssetService, type Asset, type AgentAsset, type AgentAssetWithAsset, type AccessMode, type CreateAssetParams, type PopulateAssetParams, type AttachAssetParams, type AssetServiceErrorReason, type ReadAssetBlobParams, type ListAssetBlobsParams, } from "./asset-service.js";
-export { buildAvailableSkillsStanza, type AvailableSkillEntry, } from "./available-skills-stanza.js";
+export { workflowKindHandler, workflowAuthorize, workflowDefinitionEnvelopeSchema, WORKFLOW_JSON_PATH, CAPABILITY_DECLARATIONS_JSON_PATH, type WorkflowPrincipal, type WorkflowHubPrincipal, type WorkflowSidecarPrincipal, } from "./workflow-kind.js";
+export { workflowRunKindHandler, workflowRunAuthorize, enqueueInbox, StaleInboxEnqueueError, dequeueToProcessing, readProcessingEntry, markConsumed, readOwnedMessageIds, readCommittedWorkflowRunLifecycle, readWorkflowRunLifecycle, replayProcessingToInbox, WORKFLOW_RUN_GITIGNORE_PATH, WORKFLOW_RUN_RUNS_PREFIX, WORKFLOW_RUN_EVENTS_DIR, WORKFLOW_RUN_GRANTS_FILE, WORKFLOW_RUN_AGENT_STATE_PREFIX, WORKFLOW_RUN_ADDRESSES_PREFIX, WORKFLOW_RUN_CONTROL_PREFIX, WORKFLOW_RUN_INBOX_DIR, WORKFLOW_RUN_PROCESSING_DIR, WORKFLOW_RUN_CONSUMED_DIR, WORKFLOW_RUN_WATERMARK_FILE, DEFAULT_CONSUMED_RETENTION_MS, type ClaimCheckEnvelope, type ConsumedEnvelope, type EnqueueAlreadyPresentReason, type EnqueueInboxArgs, type EnqueueInboxOutcome, type EnqueueInboxResult, type DequeueToProcessingResult, type ReadProcessingEntryResult, type MarkConsumedArgs, type MarkConsumedResult, type WorkflowRunLifecycle, type ReplayProcessingToInboxOpts, type ReplayProcessingToInboxResult, type WorkflowRunPrincipal, type WorkflowRunHubPrincipal, type WorkflowRunSidecarPrincipal, type WorkflowRunWorkflowProcessPrincipal, type WorkflowRunSupervisorPrincipal, } from "./workflow-run-kind.js";
+export { restoreWorkflowRunToAllocation, WORKFLOW_RUN_RESTORE_REFS, } from "./workflow-run-restore.js";
+export { createAssetService, AssetServiceError, DEFAULT_ASSET_REF, type AssetService, type Asset, type CreateAssetParams, type PopulateAssetParams, type AssetServiceErrorReason, type ReadAssetBlobParams, type ListAssetBlobsParams, } from "./asset-service.js";
 export { createWorkflowRunReader, type WorkflowRunReader, type WorkflowRunEvent, } from "./workflow-run-reader.js";
 export { WORKFLOW_RUN_EVENTS_FILE, splitCombinedEventLog, encodeCombinedEventLog, } from "./workflow-run-event-log.js";
-export type { AuthorizeFn, CreateRepoStoreConfig, InitRepoOpts, KindHandler, NewlyTerminalRun, Principal, RefEntry, RepoAction, RepoId, RepoStore, SubscribeKindEntry, SubscribeKindOpts, ValidatePushResult, WriteResult, } from "./repo-store/index.js";
+export type { AuthorizeFn, CommittedReads, CommittedTreeEntry, CreateRepoStoreConfig, InitRepoOpts, KindHandler, NewlyTerminalRun, Principal, RefEntry, RepoAction, RepoId, RepoStore, SubscribeKindEntry, SubscribeKindOpts, ValidatePushResult, WriteResult, } from "./repo-store/index.js";
 export { createRepoStore, subscribeKind, UserPrincipal } from "./repo-store/index.js";

package/dist/index.js

@@ -1,16 +1,24 @@
 export { createAgentRepoStore, } from "./agent-repo.js";
-export { createSessionService, SessionLaunchError, bridgeOrchestratorDeployContent, } from "./session-service.js";
+export { createSessionService, SessionLaunchError, bridgeOrchestratorDeployContent, deployCodeSourcedWorkflow, } from "./session-service.js";
+export { installAndApproveWorkflowDefinition, createDbFrozenApprovalWriter, } from "./workflow-probe-gate.js";
+export { committedReadsToSourceTree } from "./committed-source-tree.js";
 export { createEventCollectorRegistry, } from "./event-collector-registry.js";
-export { createSidecarRouter, createSidecarTokenAuthenticator, createSidecarEmitter, } from "./ws/index.js";
-export { createHubSessionLookups, parseAgentId, } from "./hub-session-lookups.js";
+export { createSidecarRouter, createSidecarCredentialResolver, createSidecarTokenAuthenticator, createSidecarEmitter, } from "./ws/index.js";
+export { createHubSessionLookups, findRoutableById, parseAgentId, resolveRoutableAddress, resolveRunIdForSession, resolveRunSessionId, runRowToRoutableRecord, } from "./hub-session-lookups.js";
 export { createHubSessionOrchestrator, } from "./hub-session-orchestrator.js";
 export { pushSourceUpdates, pushSourceUpdatesSubtree } from "./credential-push.js";
+export { createSidecarPluginRegistry, createSidecarAllocationReconciler, resolveEffectiveSidecarPlacement, } from "./sidecar-allocation/index.js";
+export { ensureWorkflowDefinitionForAsset } from "./workflow-definition-ensure.js";
+export { workflowSourceAssetMountPath } from "./workflow-closure-resolution.js";
+export { createWorkflowAllocationService, ExclusiveWorkflowPlacementError, resolveWorkflowSidecarPlacement, } from "./workflow-allocation-service.js";
+export { createWorkflowDispatchService, } from "./workflow-dispatch-service.js";
+export { listAcceptedWorkflowDispatches, listConsumedWorkflowDispatches, listReceivedWorkflowSignals, } from "./workflow-dispatch-settlement.js";
 export { skillKindHandler, skillAuthorize, skillFrontmatterSchema, getSkillIndex, } from "./skill-kind.js";
 export { packageRegistryKindHandler, packageRegistryAuthorize, asTarballEntry, validateTarballPackageJSON, TARBALLS_PREFIX, TARBALL_FILENAME_PATTERN, REGISTRY_INDEX_PATH, WORKSPACE_BUILTINS_REGISTRY, } from "./package-registry-kind.js";
-export { workflowKindHandler, workflowAuthorize, workflowDefinitionEnvelopeSchema, WORKFLOW_JSON_PATH, CAPABILITY_DECLARATIONS_JSON_PATH, WORKFLOW_GITIGNORE_PATH, } from "./workflow-kind.js";
-export { workflowRunKindHandler, workflowRunAuthorize, enqueueInbox, dequeueToProcessing, readProcessingEntry, markConsumed, readOwnedMessageIds, replayProcessingToInbox, WORKFLOW_RUN_GITIGNORE_PATH, WORKFLOW_RUN_RUNS_PREFIX, WORKFLOW_RUN_EVENTS_DIR, WORKFLOW_RUN_AGENT_STATE_PREFIX, WORKFLOW_RUN_ADDRESSES_PREFIX, WORKFLOW_RUN_CONTROL_PREFIX, WORKFLOW_RUN_INBOX_DIR, WORKFLOW_RUN_PROCESSING_DIR, WORKFLOW_RUN_CONSUMED_DIR, WORKFLOW_RUN_WATERMARK_FILE, DEFAULT_CONSUMED_RETENTION_MS, } from "./workflow-run-kind.js";
+export { workflowKindHandler, workflowAuthorize, workflowDefinitionEnvelopeSchema, WORKFLOW_JSON_PATH, CAPABILITY_DECLARATIONS_JSON_PATH, } from "./workflow-kind.js";
+export { workflowRunKindHandler, workflowRunAuthorize, enqueueInbox, StaleInboxEnqueueError, dequeueToProcessing, readProcessingEntry, markConsumed, readOwnedMessageIds, readCommittedWorkflowRunLifecycle, readWorkflowRunLifecycle, replayProcessingToInbox, WORKFLOW_RUN_GITIGNORE_PATH, WORKFLOW_RUN_RUNS_PREFIX, WORKFLOW_RUN_EVENTS_DIR, WORKFLOW_RUN_GRANTS_FILE, WORKFLOW_RUN_AGENT_STATE_PREFIX, WORKFLOW_RUN_ADDRESSES_PREFIX, WORKFLOW_RUN_CONTROL_PREFIX, WORKFLOW_RUN_INBOX_DIR, WORKFLOW_RUN_PROCESSING_DIR, WORKFLOW_RUN_CONSUMED_DIR, WORKFLOW_RUN_WATERMARK_FILE, DEFAULT_CONSUMED_RETENTION_MS, } from "./workflow-run-kind.js";
+export { restoreWorkflowRunToAllocation, WORKFLOW_RUN_RESTORE_REFS, } from "./workflow-run-restore.js";
 export { createAssetService, AssetServiceError, DEFAULT_ASSET_REF, } from "./asset-service.js";
-export { buildAvailableSkillsStanza, } from "./available-skills-stanza.js";
 export { createWorkflowRunReader, } from "./workflow-run-reader.js";
 export { WORKFLOW_RUN_EVENTS_FILE, splitCombinedEventLog, encodeCombinedEventLog, } from "./workflow-run-event-log.js";
 export { createRepoStore, subscribeKind, UserPrincipal } from "./repo-store/index.js";

package/dist/repo-store/index.d.ts

@@ -1,4 +1,4 @@
-export type { AuthorizeFn, InitRepoOpts, KindHandler, NewlyTerminalRun, PriorDeltaReads, Principal, RefEntry, RepoAction, RepoId, RepoKind, RepoStore, RepoStoreSubscribeEvent, TreeContent, ValidatePushResult, WriteResult, WriteTreePreservingPrefixArgs, } from "./types.js";
+export type { AuthorizeFn, CommittedReads, CommittedTreeEntry, InitRepoOpts, KindHandler, NewlyTerminalRun, PriorDeltaReads, Principal, RefEntry, RepoAction, RepoId, RepoKind, RepoStore, RepoStoreSubscribeEvent, TreeContent, ValidatePushResult, WriteResult, WriteTreePreservingPrefixArgs, } from "./types.js";
 export { UserPrincipal } from "./types.js";
 export { createRepoStore, type CreateRepoStoreConfig } from "./store.js";
 export { subscribeKind, type SubscribeKindOpts, type SubscribeKindEntry, } from "./subscribe-kind.js";

package/dist/repo-store/store.d.ts

@@ -1,4 +1,4 @@
-import { type CommitSigner, type GCPolicy } from "@intx/storage-isogit";
+import { type CommitSigner, type GCPolicy } from "@intx/storage-isogit/node";
 import type { AuthorizeFn, KindHandler, RepoId, RepoKind, RepoStore } from "./types.js";
 type SigningKey = {
     privateKey: Uint8Array;

package/dist/repo-store/store.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import git, {} from "isomorphic-git";
 import { createSSHSignature } from "@intx/crypto";
-import { initRepo as storageInitRepo, createDeployPack, receivePackObjects, collectReachableObjects, maybeGC, } from "@intx/storage-isogit";
+import { initRepo as storageInitRepo, createDeployPack, receivePackObjects, collectReachableObjects, maybeGC, } from "@intx/storage-isogit/node";
 import { hasCode } from "@intx/types";
 import { getLogger } from "@intx/log";
 import { SAFE_REPO_ID } from "./types.js";
@@ -638,6 +638,44 @@ export function createRepoStore(config) {
             out.set(e.path, e.oid);
         return out;
     }
+    // git tree-entry modes an admitted asset tree must not carry: a symlink can
+    // escape its directory when the tree is checked out, and a submodule gitlink
+    // is always a dangling reference (a pushed pack ships no submodule object).
+    const GIT_MODE_SYMLINK = "120000";
+    const GIT_MODE_SUBMODULE = "160000";
+    // Walk a commit's tree and return the first entry whose mode is disallowed
+    // (a symlink or a submodule), or null when the tree is clean. This mirrors
+    // the materialization backstop in `writeTreeToDisk`, but at the PUSH boundary
+    // so a directory-escaping symlink (or a dangling gitlink) is refused at
+    // admission rather than only caught later at checkout. It reads trees only,
+    // never blobs; `seen` deduplicates shared subtree oids across the commits of
+    // one pack so a subtree is walked once.
+    async function findDisallowedTreeMode(dir, treeOid, seen, prefix = "") {
+        if (seen.has(treeOid))
+            return null;
+        seen.add(treeOid);
+        const { tree } = await git.readTree({
+            fs,
+            dir,
+            cache: cacheFor(dir),
+            oid: treeOid,
+        });
+        for (const entry of tree) {
+            const entryPath = prefix === "" ? entry.path : `${prefix}/${entry.path}`;
+            if (entry.mode === GIT_MODE_SYMLINK) {
+                return { path: entryPath, kind: "symlink" };
+            }
+            if (entry.type === "commit" || entry.mode === GIT_MODE_SUBMODULE) {
+                return { path: entryPath, kind: "submodule" };
+            }
+            if (entry.type === "tree") {
+                const nested = await findDisallowedTreeMode(dir, entry.oid, seen, entryPath);
+                if (nested !== null)
+                    return nested;
+            }
+        }
+        return null;
+    }
     // Bound the set of paths a received-pack commit may have changed
     // relative to its parent, as repo-root-relative POSIX prefixes ending
     // in `/`. Git is content-addressed: a subtree whose object id is
@@ -1081,6 +1119,13 @@ export function createRepoStore(config) {
         const { priorReadBlob, priorListDir, priorListDirOids } = buildPriorTreeClosures(dir, parentCommitSha);
         const prospective = buildTreeReadClosures(dir, newRootTreeOid);
         const changedPathPrefixes = w.changedPathPrefixes;
+        // No disallowed-mode (symlink/submodule) gate here on purpose: the
+        // substrate mode gate lives on the pack-receive path. This write path
+        // cannot introduce a `120000`/`160000` entry -- `assembleTree` writes puts
+        // as `100644` and passes base-tree entries through unchanged, and no
+        // ingress ever admits such a mode into a base tree (the pack path is now
+        // gated; this path only writes `100644`). Adding a walk here would gate a
+        // tree that cannot carry those modes.
         const validation = await handler.validatePush({
             repoId,
             ref,
@@ -1325,6 +1370,7 @@ export function createRepoStore(config) {
                 existingCommitsCache.set(existingKey, existingCommits);
             }
             const newCommitsFromPack = [];
+            const newlyTerminalRuns = [];
             const oldSha = await receivePackObjects(dir, pack, ref, commitSha, transferId, expectedOldSha, 
             // A pack may carry more than one new commit (e.g. supervisor
             // bootstrap that batches enqueue + dequeue before the hub has
@@ -1340,6 +1386,9 @@ export function createRepoStore(config) {
             async () => {
                 const newCommits = await collectNewCommits(dir, commitSha, expectedOldSha, existingCommits);
                 newCommitsFromPack.push(...newCommits);
+                // Shared across the pack's commits so a subtree common to several is
+                // walked once by the disallowed-mode gate below.
+                const seenTreeOids = new Set();
                 for (const newCommit of newCommits) {
                     const { commit: parsed } = await git.readCommit({
                         fs,
@@ -1391,6 +1440,22 @@ export function createRepoStore(config) {
                     const { priorReadBlob, priorListDir, priorListDirOids } = buildPriorTreeClosures(dir, parentSha);
                     const { topLevelTreePaths, readBlob, listDir } = await buildCommitTreeClosures(dir, newCommit);
                     const changedPathPrefixes = await computeChangedPathPrefixes(dir, newCommit, parentSha);
+                    // Admission gate for EVERY kind, before the per-kind validatePush:
+                    // an asset tree carrying a symlink (which can escape its directory
+                    // at checkout) or a submodule (a dangling gitlink the pack cannot
+                    // reproduce) is refused here, so the ref never advances. No kind
+                    // legitimately pushes either; `writeTreeToDisk` rejects both at
+                    // materialization as the defense-in-depth backstop. Per-commit, so
+                    // an intermediate commit that adds a symlink a later commit deletes
+                    // is still caught.
+                    const disallowed = await findDisallowedTreeMode(dir, parsed.tree, seenTreeOids);
+                    if (disallowed !== null) {
+                        // The substrate owns the `path_violation:` prefix on the thrown
+                        // message, so the reason omits it (matching every handler reason).
+                        const reason = `${disallowed.kind} at ${disallowed.path} is not allowed in a pushed asset tree (commit ${newCommit})`;
+                        logger.debug `validatePush rejected ${repoId.kind}/${repoId.id} on ${ref} at commit ${newCommit}: ${reason}`;
+                        return { ok: false, reason };
+                    }
                     const result = await handler.validatePush({
                         repoId,
                         ref,
@@ -1407,6 +1472,9 @@ export function createRepoStore(config) {
                         logger.debug `validatePush rejected ${repoId.kind}/${repoId.id} on ${ref} at commit ${newCommit}: ${result.reason}`;
                         return { ok: false, reason: result.reason };
                     }
+                    if (result.newlyTerminalRuns !== undefined) {
+                        newlyTerminalRuns.push(...result.newlyTerminalRuns);
+                    }
                 }
                 return true;
             });
@@ -1420,6 +1488,7 @@ export function createRepoStore(config) {
             await handler.onRefUpdated({ repoId, ref, oldSha, newSha: commitSha });
             await emitRefUpdate(repoId, ref, oldSha, commitSha);
             await maybeRunGC(repoId);
+            return newlyTerminalRuns;
         });
     }
     async function createPack(principal, repoId, ref) {
@@ -1528,6 +1597,72 @@ export function createRepoStore(config) {
         gateAccess(principal, repoId, ref, "resolveRef");
         return resolveRefSha(repoDir(repoId), ref);
     }
+    // Build the committed-read closures pinned to a commit. Shared by the
+    // by-ref (`openCommittedReads`) and by-commit
+    // (`openCommittedReadsAtCommit`) entrypoints, which differ only in how
+    // they obtain and validate the commit SHA.
+    function committedReadsAt(dir, commitSha) {
+        const { readBlobByOid } = buildPriorTreeClosures(dir, commitSha);
+        const treeOid = async (relPath) => {
+            // "." and "" both name the root tree; resolveTreeEntry treats the
+            // empty string as the root, so normalize "." to it.
+            const normalized = relPath === "." ? "" : relPath;
+            return resolveTreeEntry(dir, commitSha, normalized, "tree");
+        };
+        const listDir = async (relPath) => {
+            const oid = await treeOid(relPath);
+            if (oid === null)
+                return [];
+            const { tree } = await git.readTree({
+                fs,
+                dir,
+                cache: cacheFor(dir),
+                oid,
+            });
+            return tree.map((e) => ({ name: e.path, oid: e.oid, type: e.type }));
+        };
+        return { listDir, readBlobByOid, treeOid };
+    }
+    async function repoHasGitDir(dir) {
+        return fs.promises
+            .stat(path.join(dir, ".git"))
+            .then(() => true)
+            .catch(() => false);
+    }
+    async function openCommittedReads(principal, repoId, ref) {
+        gateAccess(principal, repoId, ref, "resolveRef");
+        const dir = repoDir(repoId);
+        if (!(await repoHasGitDir(dir)))
+            return null;
+        const commitSha = await resolveRefSha(dir, ref);
+        if (commitSha === null)
+            return null;
+        return committedReadsAt(dir, commitSha);
+    }
+    async function openCommittedReadsAtCommit(principal, repoId, commitSha) {
+        // No single ref to gate on; use the same `"*"`/`resolveRef` bulk-read
+        // gate that `listRefs` and `resolveHead` use.
+        gateAccess(principal, repoId, "*", "resolveRef");
+        if (!/^[0-9a-f]{40}$/.test(commitSha)) {
+            throw new Error(`commit_sha_invalid: ${commitSha}`);
+        }
+        const dir = repoDir(repoId);
+        if (!(await repoHasGitDir(dir)))
+            return null;
+        // Confirm the commit object is present so a pruned commit reads as a
+        // clean `null` rather than a lazy throw on the first tree walk.
+        const present = await git
+            .readCommit({ fs, dir, cache: cacheFor(dir), oid: commitSha })
+            .then(() => true)
+            .catch((err) => {
+            if (hasCode(err) && err.code === "NotFoundError")
+                return false;
+            throw err;
+        });
+        if (!present)
+            return null;
+        return committedReadsAt(dir, commitSha);
+    }
     function subscribe(principal, repoId, ref, opts) {
         gateAccess(principal, repoId, ref, "resolveRef");
         const bufferLimit = opts.bufferLimit ?? DEFAULT_SUBSCRIBE_BUFFER_LIMIT;
@@ -1687,6 +1822,8 @@ export function createRepoStore(config) {
         listRefs,
         resolveHead,
         getRepoDir,
+        openCommittedReads,
+        openCommittedReadsAtCommit,
         subscribe,
     };
 }

package/dist/repo-store/subscribe-kind.d.ts

@@ -40,9 +40,12 @@ export type SubscribeKindEntry<T> = {
  * kinds filter against the inner `type` discriminator, and yields one
  * `{ seq, event }` entry per matching blob.
  *
- * The path layout is owned here, not in the substrate: the substrate
- * `subscribe` is a generic ref-tail primitive and knows nothing about
- * workflow-runs.
+ * The path-layout vocabulary (the `runs/`/`events/` prefixes and the
+ * `<seq>.json` filename shape) lives in the workflow-run kind handler,
+ * which is the authority for what may land under this prefix; this
+ * helper imports it rather than re-encoding it. The substrate
+ * `subscribe` it wraps is a generic ref-tail primitive and knows
+ * nothing about workflow-runs.
  *
  * Diff scope: the helper enumerates event blobs present in the new
  * commit but absent from the old commit. A commit that does not add

package/dist/repo-store/subscribe-kind.js

@@ -1,17 +1,5 @@
-import fs from "node:fs";
-import git from "isomorphic-git";
 import { type } from "arktype";
-import { hasCode } from "@intx/types";
-/**
- * Path-layout constants for the workflow-run repo's event log. The
- * workflow-run kind handler commits one JSON blob per event under
- * `runs/<runId>/events/<seq>.json` (the layout decided in the
- * pre-build interface decisions for the workflow-run repo). The
- * `subscribeKind` helper owns this layout so the substrate `subscribe`
- * stays generic and free of workflow-event vocabulary.
- */
-const RUNS_PREFIX = "runs";
-const EVENTS_DIR = "events";
+import { requireEventSeq, WORKFLOW_RUN_EVENTS_DIR, WORKFLOW_RUN_RUNS_PREFIX, } from "../workflow-run-kind.js";
 /**
  * Substrate envelope shape. Imported textually rather than from
  * `types.ts` so this helper has a local, validator-checked view of
@@ -24,11 +12,6 @@ const SubstrateEvent = type({
     "oldSha?": "string | null",
     newSha: "string",
 });
-/**
- * Per-event filename shape. Filenames are `<seq>.json` under
- * `runs/<runId>/events/`. `<seq>` is a non-negative decimal integer.
- */
-const EVENT_FILENAME_RE = /^(0|[1-9][0-9]*)\.json$/;
 const KindEnvelope = type({
     type: "string",
 });
@@ -41,9 +24,12 @@ const KindEnvelope = type({
  * kinds filter against the inner `type` discriminator, and yields one
  * `{ seq, event }` entry per matching blob.
  *
- * The path layout is owned here, not in the substrate: the substrate
- * `subscribe` is a generic ref-tail primitive and knows nothing about
- * workflow-runs.
+ * The path-layout vocabulary (the `runs/`/`events/` prefixes and the
+ * `<seq>.json` filename shape) lives in the workflow-run kind handler,
+ * which is the authority for what may land under this prefix; this
+ * helper imports it rather than re-encoding it. The substrate
+ * `subscribe` it wraps is a generic ref-tail primitive and knows
+ * nothing about workflow-runs.
  *
  * Diff scope: the helper enumerates event blobs present in the new
  * commit but absent from the old commit. A commit that does not add
@@ -53,7 +39,6 @@ const KindEnvelope = type({
  */
 export async function* subscribeKind(store, principal, repoId, ref, validator, opts) {
     const kindsAllowed = new Set(opts.kinds);
-    const dir = store.getRepoDir(repoId);
     const subscribeOpts = {
         signal: opts.signal,
         from: opts.from,
@@ -67,9 +52,17 @@ export async function* subscribeKind(store, principal, repoId, ref, validator, o
         if (envelope instanceof type.errors) {
             throw new Error(`subscribe_kind_envelope_invalid: ${envelope.summary}`);
         }
-        const candidates = await collectAddedEventBlobs(dir, envelope.oldSha ?? null, envelope.newSha);
+        const newReads = await store.openCommittedReadsAtCommit(principal, repoId, envelope.newSha);
+        // A commit a concurrent GC pruned between the ref-update event and
+        // this read yields nothing; the substrate surfaces that as `null`.
+        if (newReads === null)
+            continue;
+        const oldReads = envelope.oldSha === undefined || envelope.oldSha === null
+            ? null
+            : await store.openCommittedReadsAtCommit(principal, repoId, envelope.oldSha);
+        const candidates = await collectAddedEventBlobs(newReads, oldReads);
         for (const candidate of candidates) {
-            const raw = await readBlobAtCommit(dir, envelope.newSha, candidate.blobPath);
+            const raw = await newReads.readBlobByOid(candidate.oid);
             let parsedJson;
             try {
                 parsedJson = JSON.parse(new TextDecoder().decode(raw));
@@ -94,20 +87,22 @@ export async function* subscribeKind(store, principal, repoId, ref, validator, o
     }
 }
 /**
- * Walk the `runs/<runId>/events/` subtree at `newSha` and at `oldSha`
- * (when present) and return the set of event candidates present in
- * the new commit but not in the old. Filenames that fail the
- * `<seq>.json` shape are surfaced as errors rather than silently
- * skipped — the workflow-run kind handler's validatePush is the
- * authority for what may land under this prefix, so an unexpected
- * shape here is a substrate-side invariant violation.
+ * Diff the `runs/<runId>/events/` subtree between the new and old commit
+ * reads and return the event candidates present in the new commit but
+ * not the old. `oldReads` is `null` for the ref's first commit (no prior
+ * tip) or when the prior commit is no longer in the object store, in
+ * which case every event in the new commit is treated as added.
+ * Filenames that fail the `<seq>.json` shape are surfaced as errors
+ * rather than silently skipped — the workflow-run kind handler's
+ * validatePush is the authority for what may land under this prefix, so
+ * an unexpected shape here is a substrate-side invariant violation.
  */
-async function collectAddedEventBlobs(dir, oldSha, newSha) {
-    const newSet = await enumerateEventBlobs(dir, newSha);
-    if (oldSha === null) {
+async function collectAddedEventBlobs(newReads, oldReads) {
+    const newSet = await enumerateEventBlobs(newReads);
+    if (oldReads === null) {
         return [...newSet.values()].sort(byRunThenSeq);
     }
-    const oldSet = await enumerateEventBlobs(dir, oldSha);
+    const oldSet = await enumerateEventBlobs(oldReads);
     const out = [];
     for (const [key, candidate] of newSet) {
         if (oldSet.has(key))
@@ -124,56 +119,26 @@ function byRunThenSeq(a, b) {
         return 1;
     return a.seq - b.seq;
 }
-async function enumerateEventBlobs(dir, commitOid) {
+async function enumerateEventBlobs(reads) {
     const out = new Map();
-    let commit;
-    try {
-        commit = await git.readCommit({ fs, dir, oid: commitOid });
-    }
-    catch (err) {
-        if (hasCode(err) && err.code === "NotFoundError")
-            return out;
-        throw err;
-    }
-    const runsOid = await lookupSubtree(dir, commit.commit.tree, RUNS_PREFIX);
-    if (runsOid === null)
-        return out;
-    const { tree: runs } = await git.readTree({ fs, dir, oid: runsOid });
+    const runs = await reads.listDir(WORKFLOW_RUN_RUNS_PREFIX);
     for (const runEntry of runs) {
         if (runEntry.type !== "tree")
             continue;
-        const runId = runEntry.path;
-        const eventsOid = await lookupSubtree(dir, runEntry.oid, EVENTS_DIR);
-        if (eventsOid === null)
-            continue;
-        const { tree: events } = await git.readTree({ fs, dir, oid: eventsOid });
+        const runId = runEntry.name;
+        const events = await reads.listDir(`${WORKFLOW_RUN_RUNS_PREFIX}/${runId}/${WORKFLOW_RUN_EVENTS_DIR}`);
         for (const blob of events) {
             if (blob.type !== "blob")
                 continue;
-            const match = EVENT_FILENAME_RE.exec(blob.path);
-            if (match === null) {
-                throw new Error(`subscribe_kind_unexpected_event_filename: ${RUNS_PREFIX}/${runId}/${EVENTS_DIR}/${blob.path}`);
-            }
-            const seqStr = match[1];
-            if (seqStr === undefined)
-                throw new Error("unreachable");
-            const seq = Number.parseInt(seqStr, 10);
-            const blobPath = `${RUNS_PREFIX}/${runId}/${EVENTS_DIR}/${blob.path}`;
-            out.set(`${runId}/${blob.path}`, { seq, runId, blobPath });
+            const blobPath = `${WORKFLOW_RUN_RUNS_PREFIX}/${runId}/${WORKFLOW_RUN_EVENTS_DIR}/${blob.name}`;
+            const seq = requireEventSeq(blob.name, blobPath);
+            out.set(`${runId}/${blob.name}`, {
+                seq,
+                runId,
+                blobPath,
+                oid: blob.oid,
+            });
         }
     }
     return out;
 }
-async function lookupSubtree(dir, parentTreeOid, name) {
-    const { tree } = await git.readTree({ fs, dir, oid: parentTreeOid });
-    const entry = tree.find((e) => e.path === name);
-    if (entry === undefined)
-        return null;
-    if (entry.type !== "tree")
-        return null;
-    return entry.oid;
-}
-async function readBlobAtCommit(dir, commitOid, filepath) {
-    const { blob } = await git.readBlob({ fs, dir, oid: commitOid, filepath });
-    return blob;
-}