fix: resolve secret refs before sandbox draft probes (#8256)
## Thinking Path > - Paperclip is the control plane operators use to manage agent execution environments, including plugin-declared sandbox providers. > - The failing user path here was `Test draft` for an unsaved sandbox environment using a schema field marked `format: "secret-ref"`. > - Saved environments already resolve secret refs before provider use, but the unsaved probe path was forwarding the selected secret UUID directly to the provider, which made Novita draft probes fail. > - Fixing that safely required a probe-only secret resolution path with explicit actor authorization and audit context, because an unsaved draft has no persisted environment binding to authorize against. > - Once that was fixed, CI and review surfaced follow-up hardening work: preserve actor source through the draft-probe path, prevent late heartbeat finalization from overwriting already-terminal runs, avoid duplicate successful-run handoff wakes for comment-driven runs, make SSH git ref updates tolerate concurrent managed-runtime restores, and keep the skills catalog build from failing on transient GitHub errors for pinned references. > - The result is that Novita draft probes now behave like saved environments, the new secret access path is constrained and audited, and the PR is green end-to-end with Greptile at 5/5. ## Linked Issues or Issue Description No matching public GitHub issue was found after searching open and closed Paperclip issues for `novita`. Related PR search found [#8255](https://github.com/paperclipai/paperclip/pull/8255), but it addresses Novita/dev-SDK linking rather than this draft probe bug. Bug summary: - What happened? When a board user configured a sandbox environment backed by a schema-driven plugin provider such as Novita, selecting an existing company secret for `apiKey` and clicking `Test draft` failed because the probe received the secret UUID instead of the resolved secret value. - Expected behavior `Test draft` should resolve secret-ref fields before calling the provider probe, just like the saved runtime path does. - Steps to reproduce 1. Open `Company Settings -> Environments`. 2. Create or edit a `Sandbox` environment using a provider with a `format: "secret-ref"` field such as `Novita Agent Sandbox`. 3. Select an existing company secret for `apiKey`. 4. Click `Test draft`. 5. Observe the probe failure before this patch. - Paperclip version or commit Reproduced on a local `master` dev checkout; fixed and verified on branch commit `ed982d0c0`. - Deployment mode Local dev (`pnpm dev`). - Installation method Built from source (`pnpm dev` / `pnpm build`). - Agent adapter(s) involved Not adapter-specific in the core bug path; affects schema-driven sandbox provider plugins such as Novita. - Database mode Not database-related. - Access context Board (human operator). - Node.js version `v25.6.1`. - Operating system `macOS 15.7.4`. - Relevant logs or output The user-visible failure was `Novita sandbox probe failed` during `Test draft`. ## What Changed - Resolved schema-marked secret-ref fields during unsaved sandbox environment probes by adding a dedicated probe-time secret resolution path in `environment-config.ts`. - Passed `companyId` plus the full authenticated actor context into the draft probe normalization route so secret resolution stays company-scoped, authorized, and auditable. - Hardened ephemeral secret resolution so unsaved probes require `secrets:read`, preserve the original actor source (`local_implicit`, `agent_jwt`, etc.), and emit usable audit metadata. - Added a conditional heartbeat run-status update so late adapter completions cannot overwrite runs that were already cancelled or otherwise terminal. - Skipped successful-run handoff synthesis for comment-driven wakes, which removes the extra wake/run that was breaking `heartbeat-comment-wake-batching`. - Retried managed-runtime SSH git ref updates on concurrent ref-lock races instead of failing the restore path. - Reused the previous skills-catalog manifest entry when a pinned GitHub reference fails with a recoverable transient error during CI catalog generation. - Added focused regression coverage for the draft probe, ephemeral secret access, heartbeat handoff behavior, SSH ref-lock races, and catalog fallback behavior. ## Verification - `pnpm vitest run server/src/__tests__/environment-routes.test.ts` - `pnpm vitest run server/src/__tests__/secrets-service.test.ts` - `pnpm vitest run server/src/__tests__/heartbeat-comment-wake-batching.test.ts` - `pnpm vitest run server/src/services/recovery/successful-run-handoff.test.ts` - `pnpm vitest run server/src/__tests__/openclaw-gateway-adapter.test.ts` - `pnpm exec vitest run packages/adapter-utils/src/ssh-fixture.test.ts -t "merges concurrent remote commits through the managed runtime restore path"` - `pnpm exec vitest run packages/skills-catalog/src/catalog-builder.test.ts` - `pnpm --filter @paperclipai/server typecheck` - `pnpm --filter @paperclipai/skills-catalog build` - `pnpm --filter @paperclipai/adapter-utils build` - `gh pr checks 8256` - Manual/live validation: the same fix was cherry-picked into the running local dev checkout and the user re-tested the Novita `Test draft` flow successfully after the server restart. ## Risks - Low risk: the Novita-specific user-facing fix is isolated to unsaved sandbox draft probes for plugin schema fields marked `format: "secret-ref"`. - The new ephemeral secret resolution path is intentionally stricter than the original broken behavior; regressions would most likely show up as denied draft probes rather than accidental secret exposure. - The heartbeat, SSH, and catalog changes are all defensive; if they regress, they should affect test/CI orchestration paths rather than persisted company data. ## Model Used - OpenAI Codex Local (`codex_local` in Paperclip). The runtime does not expose the exact backend model ID in agent metadata. GPT-5-class coding model with shell/tool use, repository editing, test execution, GitHub review handling, and issue-thread coordination. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [ ] If this change affects the UI, I have included before/after screenshots - [ ] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Devin Foley
@@ -701,69 +701,89 @@ async function integrateImportedGitHead(input: {
|
||||
localDir: string;
|
||||
importedHead: string;
|
||||
}): Promise<void> {
|
||||
const snapshot = await readLocalGitWorkspaceSnapshot(input.localDir);
|
||||
if (!snapshot) return;
|
||||
const isConcurrentRefUpdateError = (error: unknown) => {
|
||||
const message = error instanceof Error ? error.message : String(error);
|
||||
return message.includes("cannot lock ref") && message.includes("expected");
|
||||
};
|
||||
|
||||
const currentHead = snapshot.headCommit;
|
||||
if (!currentHead || currentHead === input.importedHead) return;
|
||||
for (let attempt = 0; attempt < 5; attempt += 1) {
|
||||
const snapshot = await readLocalGitWorkspaceSnapshot(input.localDir);
|
||||
if (!snapshot) return;
|
||||
|
||||
const headRef = snapshot.branchName ? `refs/heads/${snapshot.branchName}` : "HEAD";
|
||||
const mergeBase = await runLocalGit(input.localDir, ["merge-base", currentHead, input.importedHead], {
|
||||
timeout: 10_000,
|
||||
maxBuffer: 16 * 1024,
|
||||
}).catch(() => null);
|
||||
const mergeBaseHead = mergeBase?.stdout.trim() ?? "";
|
||||
const currentHead = snapshot.headCommit;
|
||||
if (!currentHead || currentHead === input.importedHead) return;
|
||||
|
||||
if (mergeBaseHead === input.importedHead) {
|
||||
return;
|
||||
}
|
||||
|
||||
if (mergeBaseHead === currentHead) {
|
||||
await runLocalGit(input.localDir, ["update-ref", headRef, input.importedHead, currentHead], {
|
||||
const headRef = snapshot.branchName ? `refs/heads/${snapshot.branchName}` : "HEAD";
|
||||
const mergeBase = await runLocalGit(input.localDir, ["merge-base", currentHead, input.importedHead], {
|
||||
timeout: 10_000,
|
||||
maxBuffer: 16 * 1024,
|
||||
});
|
||||
return;
|
||||
}
|
||||
}).catch(() => null);
|
||||
const mergeBaseHead = mergeBase?.stdout.trim() ?? "";
|
||||
|
||||
let mergedTree;
|
||||
try {
|
||||
mergedTree = await runLocalGit(input.localDir, ["merge-tree", "--write-tree", currentHead, input.importedHead], {
|
||||
timeout: 60_000,
|
||||
maxBuffer: 256 * 1024,
|
||||
});
|
||||
} catch (error) {
|
||||
const reason = error instanceof Error ? error.message : String(error);
|
||||
throw new Error(
|
||||
`Failed to merge concurrent SSH git histories for ${currentHead.slice(0, 12)} and ${input.importedHead.slice(0, 12)}: ${reason}`,
|
||||
if (mergeBaseHead === input.importedHead) {
|
||||
return;
|
||||
}
|
||||
|
||||
if (mergeBaseHead === currentHead) {
|
||||
try {
|
||||
await runLocalGit(input.localDir, ["update-ref", headRef, input.importedHead, currentHead], {
|
||||
timeout: 10_000,
|
||||
maxBuffer: 16 * 1024,
|
||||
});
|
||||
return;
|
||||
} catch (error) {
|
||||
if (isConcurrentRefUpdateError(error) && attempt < 4) continue;
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
let mergedTree;
|
||||
try {
|
||||
mergedTree = await runLocalGit(input.localDir, ["merge-tree", "--write-tree", currentHead, input.importedHead], {
|
||||
timeout: 60_000,
|
||||
maxBuffer: 256 * 1024,
|
||||
});
|
||||
} catch (error) {
|
||||
const reason = error instanceof Error ? error.message : String(error);
|
||||
throw new Error(
|
||||
`Failed to merge concurrent SSH git histories for ${currentHead.slice(0, 12)} and ${input.importedHead.slice(0, 12)}: ${reason}`,
|
||||
);
|
||||
}
|
||||
const mergedTreeId = mergedTree.stdout.trim().split("\n")[0]?.trim() ?? "";
|
||||
if (!mergedTreeId) {
|
||||
throw new Error("Failed to compute a merged git tree for SSH workspace restore.");
|
||||
}
|
||||
|
||||
const mergeCommit = await runLocalGit(
|
||||
input.localDir,
|
||||
[
|
||||
"commit-tree",
|
||||
mergedTreeId,
|
||||
"-p",
|
||||
currentHead,
|
||||
"-p",
|
||||
input.importedHead,
|
||||
"-m",
|
||||
`Paperclip SSH sync merge ${input.importedHead.slice(0, 12)}`,
|
||||
],
|
||||
{
|
||||
timeout: 60_000,
|
||||
maxBuffer: 64 * 1024,
|
||||
},
|
||||
);
|
||||
}
|
||||
const mergedTreeId = mergedTree.stdout.trim().split("\n")[0]?.trim() ?? "";
|
||||
if (!mergedTreeId) {
|
||||
throw new Error("Failed to compute a merged git tree for SSH workspace restore.");
|
||||
try {
|
||||
await runLocalGit(input.localDir, ["update-ref", headRef, mergeCommit.stdout.trim(), currentHead], {
|
||||
timeout: 10_000,
|
||||
maxBuffer: 16 * 1024,
|
||||
});
|
||||
return;
|
||||
} catch (error) {
|
||||
if (isConcurrentRefUpdateError(error) && attempt < 4) continue;
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
const mergeCommit = await runLocalGit(
|
||||
input.localDir,
|
||||
[
|
||||
"commit-tree",
|
||||
mergedTreeId,
|
||||
"-p",
|
||||
currentHead,
|
||||
"-p",
|
||||
input.importedHead,
|
||||
"-m",
|
||||
`Paperclip SSH sync merge ${input.importedHead.slice(0, 12)}`,
|
||||
],
|
||||
{
|
||||
timeout: 60_000,
|
||||
maxBuffer: 64 * 1024,
|
||||
},
|
||||
);
|
||||
await runLocalGit(input.localDir, ["update-ref", headRef, mergeCommit.stdout.trim(), currentHead], {
|
||||
timeout: 10_000,
|
||||
maxBuffer: 16 * 1024,
|
||||
});
|
||||
throw new Error(`Failed to integrate concurrent SSH git history for ${input.importedHead.slice(0, 12)} after multiple retries.`);
|
||||
}
|
||||
|
||||
async function clearRemoteDirectory(input: {
|
||||
|
||||
@@ -135,6 +135,93 @@ describe("skills catalog manifest", () => {
|
||||
expect(result.manifest.skills[0]!.contentHash).toMatch(/^sha256:[a-f0-9]{64}$/);
|
||||
});
|
||||
|
||||
it("reuses the existing manifest entry when a pinned GitHub reference is temporarily unavailable", async () => {
|
||||
const packageDir = await createCatalogPackage();
|
||||
await writeReference(packageDir, "optional", "research", "remote-research", {
|
||||
source: {
|
||||
type: "github",
|
||||
hostname: "github.com",
|
||||
owner: "example",
|
||||
repo: "remote-skill",
|
||||
ref: "v1.0.0",
|
||||
commit: "0123456789abcdef0123456789abcdef01234567",
|
||||
path: "skills/remote-research",
|
||||
},
|
||||
files: ["SKILL.md", "scripts/**"],
|
||||
recommendedForRoles: ["researcher"],
|
||||
tags: ["research"],
|
||||
});
|
||||
await fs.mkdir(path.join(packageDir, "generated"), { recursive: true });
|
||||
await fs.writeFile(
|
||||
path.join(packageDir, "generated", "catalog.json"),
|
||||
formatCatalogManifest({
|
||||
schemaVersion: 1,
|
||||
packageName: "@paperclipai/skills-catalog",
|
||||
packageVersion: "0.3.1",
|
||||
generatedAt: "2026-05-26T00:00:00.000Z",
|
||||
skills: [{
|
||||
id: "paperclipai:optional:research:remote-research",
|
||||
key: "paperclipai/optional/research/remote-research",
|
||||
kind: "optional",
|
||||
category: "research",
|
||||
slug: "remote-research",
|
||||
name: "Remote Research",
|
||||
description: "Research recent discussion from a pinned upstream skill.",
|
||||
path: "catalog/optional/research/remote-research",
|
||||
entrypoint: "SKILL.md",
|
||||
trustLevel: "scripts_executables",
|
||||
compatibility: "compatible",
|
||||
defaultInstall: false,
|
||||
recommendedForRoles: ["researcher"],
|
||||
requires: [],
|
||||
tags: ["research"],
|
||||
files: [
|
||||
{
|
||||
path: "SKILL.md",
|
||||
kind: "skill",
|
||||
sizeBytes: 128,
|
||||
sha256: "a".repeat(64),
|
||||
},
|
||||
{
|
||||
path: "scripts/run.py",
|
||||
kind: "script",
|
||||
sizeBytes: 14,
|
||||
sha256: "b".repeat(64),
|
||||
},
|
||||
],
|
||||
contentHash: `sha256:${"c".repeat(64)}`,
|
||||
source: {
|
||||
type: "github",
|
||||
hostname: "github.com",
|
||||
owner: "example",
|
||||
repo: "remote-skill",
|
||||
ref: "v1.0.0",
|
||||
commit: "0123456789abcdef0123456789abcdef01234567",
|
||||
path: "skills/remote-research",
|
||||
url: "https://github.com/example/remote-skill/tree/v1.0.0/skills/remote-research",
|
||||
},
|
||||
}],
|
||||
}),
|
||||
"utf8",
|
||||
);
|
||||
vi.stubGlobal("fetch", vi.fn(async (url: string) => {
|
||||
if (url.includes("/git/trees/")) {
|
||||
return new Response("forbidden", { status: 403 });
|
||||
}
|
||||
return new Response("not found", { status: 404 });
|
||||
}));
|
||||
|
||||
const result = await buildCatalogManifest({
|
||||
packageDir,
|
||||
generatedAt: "2026-05-26T00:00:00.000Z",
|
||||
});
|
||||
|
||||
expect(result.errors).toEqual([]);
|
||||
expect(result.manifest.skills).toHaveLength(1);
|
||||
expect(result.manifest.skills[0]?.name).toBe("Remote Research");
|
||||
expect(result.manifest.skills[0]?.files.map((file) => file.path)).toEqual(["SKILL.md", "scripts/run.py"]);
|
||||
});
|
||||
|
||||
it("reports frontmatter, directory, uniqueness, and inventory errors together", async () => {
|
||||
const packageDir = await createCatalogPackage();
|
||||
await writeSkill(packageDir, "bundled", "Bad_Category", "duplicate", {
|
||||
|
||||
@@ -101,6 +101,8 @@ export async function buildCatalogManifest(
|
||||
): Promise<BuildCatalogManifestResult> {
|
||||
const packageDir = path.resolve(options.packageDir);
|
||||
const packageJson = await readPackageJson(packageDir);
|
||||
const existingManifest = await readExistingManifest(packageDir);
|
||||
const existingSkillsById = new Map(existingManifest?.skills.map((skill) => [skill.id, skill]) ?? []);
|
||||
const errors: string[] = [];
|
||||
const candidates = await discoverSkillCandidates(packageDir, errors);
|
||||
const skills: CatalogSkill[] = [];
|
||||
@@ -108,7 +110,12 @@ export async function buildCatalogManifest(
|
||||
collectCandidateUniquenessErrors(candidates, errors);
|
||||
|
||||
for (const candidate of candidates) {
|
||||
const skill = await buildCatalogSkill(packageDir, candidate, errors);
|
||||
const skill = await buildCatalogSkill(
|
||||
packageDir,
|
||||
candidate,
|
||||
errors,
|
||||
existingSkillsById.get(skillIdForCandidate(candidate)) ?? null,
|
||||
);
|
||||
if (skill) skills.push(skill);
|
||||
}
|
||||
|
||||
@@ -253,9 +260,10 @@ async function buildCatalogSkill(
|
||||
packageDir: string,
|
||||
candidate: SkillCandidate,
|
||||
errors: string[],
|
||||
existingSkill: CatalogSkill | null,
|
||||
): Promise<CatalogSkill | null> {
|
||||
if (candidate.source === "reference") {
|
||||
return buildReferencedCatalogSkill(packageDir, candidate, errors);
|
||||
return buildReferencedCatalogSkill(packageDir, candidate, errors, existingSkill);
|
||||
}
|
||||
|
||||
const prefix = relativePackagePath(packageDir, candidate.absolutePath);
|
||||
@@ -316,10 +324,15 @@ async function buildCatalogSkill(
|
||||
};
|
||||
}
|
||||
|
||||
function skillIdForCandidate(candidate: BaseSkillCandidate) {
|
||||
return `paperclipai:${candidate.kind}:${candidate.category}:${candidate.slug}`;
|
||||
}
|
||||
|
||||
async function buildReferencedCatalogSkill(
|
||||
packageDir: string,
|
||||
candidate: Extract<SkillCandidate, { source: "reference" }>,
|
||||
errors: string[],
|
||||
existingSkill: CatalogSkill | null,
|
||||
): Promise<CatalogSkill | null> {
|
||||
const prefix = relativePackagePath(packageDir, candidate.absolutePath);
|
||||
validateSlug("category", candidate.category, prefix, errors);
|
||||
@@ -332,10 +345,26 @@ async function buildReferencedCatalogSkill(
|
||||
const key = `paperclipai/${candidate.kind}/${candidate.category}/${candidate.slug}`;
|
||||
const source = buildCatalogSkillSource(descriptor.source, errors, `${prefix}/${CATALOG_REFERENCE_FILE}`);
|
||||
if (!source) return null;
|
||||
const fallbackSkill = canReuseExistingReferencedSkill(
|
||||
existingSkill,
|
||||
candidate,
|
||||
source,
|
||||
toPosixPath(path.relative(packageDir, candidate.absolutePath)),
|
||||
)
|
||||
? existingSkill
|
||||
: null;
|
||||
const errorStart = errors.length;
|
||||
|
||||
const files = await collectReferencedSkillFiles(source, descriptor.files ?? [SKILL_ENTRYPOINT], prefix, errors);
|
||||
const skillMarkdown = await readReferencedFileText(source, SKILL_ENTRYPOINT, prefix, errors);
|
||||
if (!skillMarkdown) return null;
|
||||
if (!skillMarkdown) {
|
||||
const nextErrors = errors.slice(errorStart);
|
||||
if (fallbackSkill && canFallbackToExistingReferencedSkill(nextErrors)) {
|
||||
errors.splice(errorStart, nextErrors.length);
|
||||
return fallbackSkill;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
const parsed = parseFrontmatterMarkdown(skillMarkdown);
|
||||
if (!parsed.hasFrontmatter) {
|
||||
@@ -366,7 +395,14 @@ async function buildReferencedCatalogSkill(
|
||||
if (!files.some((file) => file.path === SKILL_ENTRYPOINT && file.kind === "skill")) {
|
||||
errors.push(`${prefix} referenced inventory does not contain SKILL.md.`);
|
||||
}
|
||||
if (!name || !description) return null;
|
||||
if (!name || !description) {
|
||||
const nextErrors = errors.slice(errorStart);
|
||||
if (fallbackSkill && canFallbackToExistingReferencedSkill(nextErrors)) {
|
||||
errors.splice(errorStart, nextErrors.length);
|
||||
return fallbackSkill;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
return {
|
||||
id,
|
||||
@@ -390,6 +426,50 @@ async function buildReferencedCatalogSkill(
|
||||
};
|
||||
}
|
||||
|
||||
function canReuseExistingReferencedSkill(
|
||||
existingSkill: CatalogSkill | null,
|
||||
candidate: Extract<SkillCandidate, { source: "reference" }>,
|
||||
source: CatalogSkillSource,
|
||||
expectedPath: string,
|
||||
) {
|
||||
if (!existingSkill || existingSkill.source?.type !== "github") return false;
|
||||
const existingSource = existingSkill.source;
|
||||
return (
|
||||
existingSkill.id === skillIdForCandidate(candidate) &&
|
||||
existingSkill.path === expectedPath &&
|
||||
existingSource.hostname === source.hostname &&
|
||||
existingSource.owner === source.owner &&
|
||||
existingSource.repo === source.repo &&
|
||||
existingSource.ref === source.ref &&
|
||||
existingSource.commit === source.commit &&
|
||||
existingSource.path === source.path
|
||||
);
|
||||
}
|
||||
|
||||
function canFallbackToExistingReferencedSkill(errors: string[]) {
|
||||
if (errors.length === 0) return false;
|
||||
const hasRecoverableFetchError = errors.some((error) => isRecoverableReferencedFetchError(error));
|
||||
return (
|
||||
hasRecoverableFetchError &&
|
||||
errors.every((error) =>
|
||||
isReferencedFetchError(error) ||
|
||||
error.includes("referenced inventory does not contain SKILL.md."),
|
||||
)
|
||||
);
|
||||
}
|
||||
|
||||
function isReferencedFetchError(error: string) {
|
||||
return error.includes("failed to fetch GitHub tree:") || error.includes("failed to fetch pinned GitHub file:");
|
||||
}
|
||||
|
||||
function isRecoverableReferencedFetchError(error: string) {
|
||||
if (!isReferencedFetchError(error)) return false;
|
||||
const statusMatch = /HTTP (\d+)/.exec(error);
|
||||
if (!statusMatch) return true;
|
||||
const status = Number(statusMatch[1]);
|
||||
return status === 403 || status === 408 || status === 409 || status === 425 || status === 429 || status >= 500;
|
||||
}
|
||||
|
||||
async function readReferencedSkillDescriptor(
|
||||
descriptorPath: string,
|
||||
prefix: string,
|
||||
|
||||
Reference in New Issue
Block a user